Day in the Life of a Technical Writer: Three Real Days

Coffee. I make it with a pour-over kit I've had for four years. Six minutes. I don't rush this. Gwen the old agency version of me would have been on Slack before the kettle boiled. I am working on not being that person.

Open Slack. Catch up on engineering channels from last night. Soren, who's one of the backend engineers, dropped a note in #dev-discussion at 11:20 PM about a change to how the CLI handles config file precedence. The new behavior affects a guide I published three weeks ago. The guide currently says local config overrides environment variables. Under the new behavior, it's the opposite. I add it to my list.

Stand-up. Ten minutes. Three people talk about what they're working on. My PM Fiona asks me where I am on the new onboarding guide. I tell her first draft by Friday. She says Thursday would be better. I say the Thursday version will be incomplete and the Friday version will be complete, and she can choose. She picks Friday. We've done this before. She always picks the complete one. I think she asks for Thursday because she's calibrating for exactly this conversation.

Jira. Nine tickets in the docs backlog with my name on them. Four are labeled "sprint priority." I read through each one and pick the highest-impact item: an update to the authentication guide after last week's OAuth 2.0 changes. I put the others back in the stack for now. You can't do all of it. You pick what matters most today.

Open the authentication guide. It's 1,800 words. The OAuth changes affect about 400 of them, specifically the sections on token refresh and scope configuration. I open the GitHub PR that shipped the changes alongside the doc, read the diff. Soren again. He has a habit of shipping things at 9 PM on Tuesdays. His code is clean and his commit messages are good. The commit message says "update refresh token behavior, reduce scope validation calls." I need to understand what "reduce scope validation calls" means for users configuring their OAuth apps.

Slack message to Soren: "Hey, re: the refresh token PR, in the new behavior, does the client need to explicitly request the 'offline_access' scope to get a refresh token, or is that automatic now?" Within eight minutes: "automatic if you set refresh_enabled: true in the app config, but only if the user has previously granted the scope in a prior auth flow." OK. That changes part of my guide. And it raises a new question.

Follow-up to Soren: "What happens on first-time auth where there's no prior grant?" He responds in four minutes: "It falls back to requiring explicit offline_access scope on the first flow, then auto on subsequent." Got it. That's a two-scenario structure for the guide. I open a scratch doc and write out the two paths before I touch the actual guide. I've learned to do this. Going directly into the published doc and revising in-place means I lose track of what I've changed and what I haven't.

Writing. The two-scenario structure for the refresh token section. First-time auth flow. Subsequent auth flow. The config setup that unlocks automatic behavior. A warning box about the prior-grant dependency, because if someone sets refresh_enabled: true and doesn't understand the first-time grant requirement, they'll get unexpected behavior and file a support ticket. I know what those tickets look like. I filed one summary of them last quarter.

I've rewritten about 350 words of the authentication guide. It's better. The two-scenario structure is clearer than the old single-path narrative that assumed everyone had already done a prior auth flow. I send the revised section to Soren in Slack and ask him to scan it for accuracy. He says he'll look at it after his 11:30. OK.

Switch contexts. The CLI config precedence issue Soren posted last night. I go into our staging environment, which lives in a Docker container I keep running on my dev machine, and I test the new behavior. I set up three config files at different scope levels: global, project-level, local. Then I run the CLI and observe which config wins. The result confirms what Soren described: environment variables now take precedence over local config. That's a breaking change for any user who's relying on local config to override a CI/CD environment variable. I write a note for the release notes and add a callout to the guide update queue. Breaking change callout, not just a quiet update.

Lunch. Leftovers from Monday. I eat at my desk and read through the Write the Docs Slack, which is a community of technical writers I've been part of for three years. Someone's asking about Markdown linting tools. I know the answer and I type it. This takes five minutes and I don't mind because the community has given me answers I needed at 9:30 AM on a Tuesday when no one else was available.

Soren responds to my authentication section draft. Two small corrections: one where I described the scope as a string and it's actually an array, and one where I used "returns" when the correct term is "issues." I fix both. I publish the updated guide. I note the time: 12:46 PM. Three and a half hours from Soren's commit message to corrected live documentation. That's not bad for a behavior change with two edge cases.

Onboarding guide. This is the Friday deliverable. It covers how new developers set up a local dev environment and make their first API call. I've been building it from scratch. I have a completed outline and about 60% of the content drafted. Today I need to write the environment setup section, which covers three operating systems and two package managers. I've been putting this off because it's tedious and branching.

I actually do it. I've learned not to reorganize my desk or get another coffee instead of doing the tedious thing. Mac and Linux together. Windows in a separate tabbed section. Homebrew and npm side by side. I set up each path in the staging environment as I write about it, confirming that the steps work as I describe them. Setting up the Windows path takes 34 minutes because I have a Windows VM and Windows is always more steps.

Fiona Slacks me: "Can you add a section on how to get an API key before the first call? Sales had a call with a prospect and they realized the onboarding guide doesn't cover that." She's right. It doesn't. I add it to the outline and draft it. It's a short section, about 200 words. I resent the timing slightly but the feedback is valid.

Review session with Priya in customer success. She does onboarding calls and she's going to use this guide once it's published. We go through the outline together on a Zoom call. She catches two places where I assumed the user had already done something I hadn't told them to do. This is the thing I'm most susceptible to after a week inside a product: invisible prerequisites. You stop seeing the things that need to be said because you know them.

Update the guide with Priya's notes. Two added prerequisites, one reordered step.

Add the CLI config precedence breaking change callout to the release notes draft. I want it labeled clearly. Not buried in a changelog line. A callout block that says "behavior change" and explains what changed and what users need to do. If a user hits this without warning, they'll spend an hour debugging CI/CD pipeline failures that are actually caused by our change. I write it in five minutes. The five minutes might save 400 user-hours across our install base. I can't know that. I believe it's true.

Close the laptop. Tell my partner Sebastien I updated three documents and confirmed three edge cases and attended two meetings and wrote about 900 new words. He asks what I want for dinner. I say I want something that doesn't involve any documentation. We have soup. It's fine.

Drive in. Twenty-two minutes. I am one of six people on my team who works from the office three days a week. I like the separation. When I'm in the building, I'm working. When I'm home, I'm not. Some people on the team can't make that split work remotely. I can't either, so I don't try.

Desk. I have a second monitor I brought from home that's four inches wider than the standard issue. This matters more than you'd think. I have three documents open and a browser tab for our docs portal and a Jira board and a browser tab with the staging environment. You need screen space.

Email. Seven messages since yesterday. One from Marguerite, the product manager on the query optimizer team, asking if I can review her first draft of the release notes for v9.4.2. She's been writing her own release notes lately because the team is shipping faster than our queue can absorb. Her drafts are always technically accurate and they read like engineering notes. My job is to translate them into something a DBA at a healthcare company can understand at 8 AM before their first coffee. I say yes, send it over.

My main task today is a legacy guide update. The index maintenance guide for v7.x. We're still supporting v7 for another 18 months and there's a known gap in the documentation around partial index behavior with NULL values. Support has flagged it four times. It's on my list. Today I'm going to fix it.

Read the support tickets. I pull the four that mention partial indexes and NULL values. They're all the same root issue: users are creating partial indexes with IS NOT NULL conditions expecting the index to exclude NULLs from result sets, and they're surprised when NULLs appear in queries that logically shouldn't touch the index. The documentation currently says partial indexes "narrow the scope of the index." That's true but it doesn't address the NULL behavior specifically, which is a known and somewhat counterintuitive aspect of how the query planner handles it.

Before I write, I need to confirm my understanding is correct. I was a database administrator for nine years. I believe I understand this behavior. I don't write from belief. I test it. I spin up a v7.x instance in our documentation testing environment, create a table with a nullable column, create a partial index on that column with IS NOT NULL, and run a query I expect to use the index. I check the query plan with EXPLAIN. I try four variations: a range query, an equality check, a join, and a subquery. I document each result in a scratch file. Takes 35 minutes.

I now know exactly what the documentation needs to say. There are two things: first, that a partial index with a WHERE IS NOT NULL condition does not exclude NULLs from queries that don't use the index, because the index is a performance artifact, not a data filter. Second, that users who want to exclude NULLs from query results should use an explicit WHERE clause in their query, not rely on index conditions. Neither of these is complicated. Both of them would have saved those four support callers several hours.

Writing. I add a new section to the index maintenance guide: "Partial Indexes and NULL Value Behavior." It's 340 words. I include a code example showing the test case I ran, the query plan output, and the correct pattern for filtering NULLs. I also add a "common misunderstanding" callout box. My manager Henrik has a philosophical objection to callout boxes overuse. He thinks they're a documentation crutch. He's not entirely wrong. But this is one of the cases where a callout box is appropriate: a counterintuitive behavior that causes support calls, with a clear correct alternative. This is exactly what callout boxes are for.

Marguerite's release notes draft arrives. I read it once all the way through. It's eight bullet points, technically accurate, written in active voice with good specificity. The problem is the order. The first item is a performance optimization for hash joins. That's important to the engineering team. The DBA using the software cares most about the first item I see, which is buried at item six: the behavior change for auto-vacuum thresholds. A behavior change affects existing configurations. That needs to be first or near first, clearly labeled as a change. I restructure the list, promote the behavior change, add a "behavior change" label. Send back with a note explaining why.

Henrik stops by my desk and asks how the partial index guide is going. I tell him it'll be done today. He asks if there's anything else in the v7.x backlog I want to flag. There are three more items on my list, smaller than the NULL issue. I show him. He says to hit the NULL one today and triage the others for next sprint. I agree. He walks away. The whole interaction takes four minutes. This is what a good manager does: they give you a decision and trust you with the execution.

Review my 340 words. Read them out loud. This is something I started doing six years ago and it's caught more errors than any other review technique I've tried. Awkward phrasing sounds awkward when you say it. Unclear steps become obvious when you're reciting them out loud and you realize you don't know what "then" refers to. I catch one place where I wrote "the index condition" when I meant "the index filter predicate" and that distinction matters for technical precision with this audience. Fix it.

Publish the partial index guide update. File a note in the support ticket system linking to the updated section. The support engineers can now point callers to the new content instead of trying to explain the behavior over the phone. Took me about two hours of actual work to fix something that's been causing support calls for eighteen months. The lag between "known gap" and "fixed gap" was not two hours. It was wait time in a queue. That's the thing nobody sees.

Lunch in the cafeteria. I eat with Lorena from the data modeling docs team and a newer writer named Bastian who joined eight months ago. Bastian is asking about how to get faster responses from engineers for technical review. I tell him to never ask an open-ended question. Send a specific hypothesis and ask them to confirm or correct it. They'll correct a wrong statement faster than they'll answer a blank question. Lorena agrees. This is the kind of thing you learn in year two and wish someone had told you in year one. We tell Bastian.

Afternoon block. I use this for longer writing, the documentation that requires sustained concentration rather than reactive updating. Today I'm working on a new "getting started with index strategy" guide that doesn't exist yet. It's been on the roadmap for two quarters. I'm building it from an outline I finalized last week. The audience is DBAs who are new to our product. The goal is a guide that helps them understand when to use which index type, with concrete examples from realistic schemas.

I write for 90 minutes without stopping. This is the part of the day I protect most carefully. I have my Slack on do-not-disturb. Only Henrik and Marguerite can break through. Nobody does today. I produce about 1,100 words. Section one is complete: when to index. Section two, what type of index, is half-drafted. The examples are good. They use a realistic e-commerce schema because that's the most common schema DBAs encounter and it makes the index decisions concrete rather than abstract.

Back to reactive mode. Three Slack messages I missed. One from a developer asking about a docs error they found, a wrong parameter name in the v9.3 API reference. I look it up. They're right. I fix it in four minutes and reply: "Fixed, thanks for catching it." No performance. Just fixed.

Marguerite responds to my release notes revision. She says the restructured order makes sense and asks why behavior changes should go first. I write a two-paragraph response. In the first paragraph I give the practical reason: it's the thing most likely to break something in a reader's existing setup, so it needs to be the first thing they process, not something they notice after they've already skimmed past it. In the second paragraph I give the general principle: release notes are read by people who are deciding whether and how to upgrade. The order should match the importance of the decision, not the importance to the engineering team.

Drive home. Mireille, my wife, asks how work was. I say I fixed a documentation gap that's been causing support calls for eighteen months and started a new guide I've been meaning to write for two quarters and revised someone's release notes and confirmed some database behavior I thought I knew but needed to verify. She says "so a good day?" I say yeah, a good day. Pretty much a standard good day.

Open my laptop at the kitchen table. My roommate Annika is getting ready for work. She's a nurse at Hennepin Healthcare. She leaves by 8:20 for a 7 AM shift that she's been doing for four years, which means she's an hour late today for some reason I don't ask about. I have three Slack notifications from last night that I'm ignoring until I've had breakfast.

Actually open Slack. Two are routine. The third is from our CTO, Ian, at 11:48 PM. He's added a comment in Notion on a doc I submitted for review: "this section on the webhook retry logic needs to clarify the exponential backoff ceiling. what's the max wait time?" I check the Notion comment thread. He's right. I wrote about exponential backoff in the webhook docs but I didn't specify the ceiling, which is actually important because if a receiving server is down, users need to know how long they should wait before assuming the retry has given up.

I look for the ceiling in our codebase. I have read access to the repo; I got that set up in my first month. I find the retry configuration in the webhook service. The ceiling is 3,600 seconds (one hour) with a base delay of 10 seconds and an exponential multiplier of 2. So the sequence is: 10s, 20s, 40s, 80s, and so on up to 3,600s max, then retries stop after the 7th attempt. That's the information I need. I add it to the doc.

Respond to Ian in the thread: "Added the backoff ceiling and retry count. Max wait is 3,600 seconds (1hr), max attempts 7. Also added a table showing the sequence of wait times for first 7 retries in case it's useful." He replies with a thumbs up emoji within three minutes. The webhook doc is done. I submit it for final publication.

Sprint planning. We do it every other Thursday. I'm in for the first 30 minutes of the 90-minute meeting. My items are straightforward: two doc tickets I own this sprint, one carry-over from last sprint. I estimate times. No one challenges them. Our PM Delphine is good at factoring in TW time since I sat down with her in month two and walked through what documentation actually takes. That conversation was worth more than any other investment I've made here.

Drop out of planning (I'm only needed for the first segment). Main task today: the user role permissions guide. We have six user roles. The permissions guide is supposed to explain what each role can do. Simple, right. Except the roles were added over three separate releases and nobody documented them holistically. There are three places in the existing docs that mention roles: the admin setup guide, the team management guide, and a FAQ. They're inconsistent with each other. My job today is to write a single authoritative permissions guide and remove the inconsistent mentions from the other docs.

Before writing, I test every role in the staging environment. I create test accounts for each of the six roles and try to perform 12 different actions with each one. I've made a spreadsheet. Each cell is a role-action combination with a checkmark or an X. Takes 55 minutes. I find two places where the actual permission behavior doesn't match what's described in the existing admin setup guide. One is minor (a billing-view permission that was added without updating the docs). One is significant: the Team Manager role has access to an integration settings page that the docs say requires Admin access. That's an undocumented permission escalation. I file a bug ticket and make a note in my draft.

Slack Ian about the integration settings discrepancy. He checks. Responds 18 minutes later: "yeah that's intentional, Team Managers need integration access for certain workflows. we should update the docs not the product." Good. My docs, not a bug. I update my spreadsheet and write "confirmed intentional, doc update needed" in the notes column.

Writing. The permissions guide. I structure it around tasks, not roles: "If you want to manage billing," "If you want to set up integrations," "If you want to invite users." Then I show which roles can do each thing. My UX research background is useful here. Users don't think about roles. They think about tasks. The role question comes up when someone can't do something and they're trying to figure out why. The guide should answer the question they're actually asking: "I'm trying to do X and it's not working, is this a permissions issue?"

Lunch. I make a sandwich. Annika texted: she was late because a patient from her last shift was re-admitted and she stayed to help with handoff. I tell her I found an undocumented permission escalation. She says "is that bad?" I say "for documentation purposes, no, because now it's documented. For security review purposes, maybe, but that's Ian's problem." She says "your job sounds like mine but with less blood." I consider this. She's not wrong about the proportions.

Back to the permissions guide. I finish the first draft. About 1,400 words plus a table. I read it through once. It's good. It's task-oriented, specific, and it uses the actual role names consistently throughout. The old docs used "admin" sometimes and "Administrator" sometimes and one page called it "admin-level user." The new guide says "Administrator" every time. Consistency might be the least glamorous achievement in TW. It still matters.

Remove the inconsistent role mentions from the admin setup guide and the team management guide. Replace with links to the new permissions guide. The FAQ entry I just delete and replace with a link. Old inconsistent content coming down and a single source of truth going up. Three years ago in my UX research job, we called this "reducing cognitive load." Now I just call it "fixing the docs."

Peer review. I don't have a TW team here, but I have Delphine, who I've trained to review for user comprehension. She reads the guide and marks two places where she wasn't sure what she was supposed to do with the information. Good feedback. I revise those sections to be more actionable.

Submit the permissions guide for publication. File the billing-view permission ticket as a quick doc update. Update Jira to reflect the sprint progress. Two tasks done, one carry-over still in progress.

Slow end to the day. I use the time to organize my backlog: the carry-over item, the new doc Ian wants next sprint, the permissions-related FAQ I need to write now that the main guide exists. None of this is writing. It's triage. I'm deciding what matters most. TW at a startup is partly writing and partly deciding which writing matters most with limited time. You get better at this the longer you do it. I'm getting better at it.

Close the laptop. I tell my friend Yasmin I found an undocumented permission escalation, fixed three inconsistent guides, and wrote 1,400 words of new documentation. She asks what technical writing is. I say it's learning how a complex product works and explaining it to someone who doesn't know. She says "like a translator?" I say yes, kind of. She says "I didn't know translators wrote software manuals." I say that's not exactly it but I let it go. She's close enough.