Technical Writer

I start by using the product myself if it's available, because clicking through something teaches me more in ten minutes than reading a spec does. I make a list of every question I can't answer from using it: edge cases, error states, what happens if I do something in the wrong order. Then I take that list to the engineer or product manager who built it, rather than asking them to explain the whole feature from scratch, because a specific question gets a specific, useful answer and respects their time. I also read any existing tickets, design docs, or Slack threads about the feature, since a lot of the reasoning behind a decision lives there rather than in the final spec. Once I have a working model of the feature, I write a rough outline and share it early, before I've invested time in full prose, so any misunderstanding gets caught while it's cheap to fix. I did this recently for a permissions system with several inherited roles: I built a small table mapping role to access level before writing a single sentence of the actual guide, because I needed to understand the logic myself before I could explain it to anyone else.

I edit in stages rather than trying to catch everything in one pass. The first pass is structural: does the document answer the question the reader came with, and is the information in the order they'd need it, not necessarily the order it was explained to me. I check that headings work as a standalone table of contents, since a lot of readers scan rather than read top to bottom. The second pass is accuracy: I walk through every instruction myself, step by step, exactly as written, because it's very easy to skip a step mentally when you already know how something works. I've caught missing steps this way that would have completely blocked a reader. The third pass is language: cutting unnecessary words, checking terminology is consistent with our style guide and glossary, and making sure I haven't used two different terms for the same thing. I use Vale for automated style and terminology checks before a human review, which catches a lot of small inconsistencies without needing a person to spot them manually. Before publishing, I ask someone unfamiliar with the feature, often someone from a different team, to follow the doc cold and tell me where they got stuck.

I start from the task the reader is trying to complete, not from everything I know about the feature. A developer integrating an API needs request and response examples, authentication details, and error codes; they don't need the backstory of why the endpoint was designed a certain way unless it affects how they use it. An end user reading a help article needs plain steps and screenshots, and technical implementation detail would just get in the way. When I'm not sure who the audience is, I ask the requester directly rather than guessing, because writing for the wrong reader wastes the effort twice, once to write it and once to rewrite it. For mixed audiences I sometimes split a document: a quick-start section for someone who wants to get moving immediately, and a reference section underneath for someone who needs the full detail. I also pay attention to what support tickets and community forum questions are actually asking, because that tells me where the real confusion is happening rather than where I assume it is. If nobody has ever asked a question about a section, that's often a sign it can be shorter.

The biggest lever is making documentation part of the release process rather than something that happens after the fact. I push for docs to be a checklist item before a feature ships, not a follow-up task, because docs written after launch consistently get deprioritised once the team moves on to the next thing. I work in Markdown with our docs stored alongside the codebase in Git, so a documentation update can go through the same pull request as the code change, and reviewers see both together. For areas that change often, like API reference docs, I generate as much as possible directly from the OpenAPI spec rather than hand-writing content that will drift out of sync. I also do a periodic audit, going through the highest-traffic pages every quarter and checking they still match the current product, because even a good process misses things occasionally. When I find outdated content during support or feedback review, I fix it immediately rather than filing it away for later, since a small fix takes minutes and a backlog of stale docs takes days to work through.

I was documenting a data export feature where two engineers gave me different answers about what happened to deleted records: one said they were excluded automatically, the other said they were included unless manually filtered. Rather than picking one answer and hoping it was right, I set up a quick test myself: I created a record, deleted it, and ran the export to see what actually happened. That settled the factual question in about fifteen minutes, faster than continuing to go back and forth over Slack. It turned out neither engineer was fully right: deleted records were excluded by default but reappeared if a certain filter was set, which was an edge case nobody had mentioned. I documented that specific behaviour clearly, including the edge case, and flagged it to the team as something worth confirming was intentional, since it wasn't obvious it should work that way. The lesson I took from it is that when sources disagree, testing the actual product is often faster and more reliable than trying to arbitrate between two people's memories of how something was built.

An engineer wanted the API reference to include every internal parameter available on an endpoint, including several that were used for internal debugging and weren't meant for external developers. My concern was that including them would create support tickets from developers trying to use parameters that weren't actually supported for external use, and it would clutter the page for the parameters people needed. I didn't just say no: I pulled up three examples from our support queue where similar undocumented-but-visible parameters had caused confusion in another part of the docs, to make the case concrete rather than a matter of opinion. I proposed a compromise: keep the public reference clean, and maintain a separate internal-only page linked from our engineering wiki for anyone on the team who needed the full parameter list. The engineer agreed once they saw the support ticket pattern, and the internal page turned out to be useful for onboarding new engineers too. I've found that pushback lands better when it's backed by a specific example of what went wrong before, rather than a general preference for simplicity.

Our support team flagged that a specific setup step, connecting a third-party calendar integration, was generating a steady stream of tickets, roughly fifteen a week according to their tagging system. I read through a sample of the tickets and noticed the existing doc assumed the reader already knew where to find their calendar's API key, which wasn't obvious at all for less technical users. I rewrote the section with a screenshot-led walkthrough for the two most common calendar providers, added a troubleshooting section addressing the three specific error messages that came up most often in the tickets, and moved the doc higher in the help centre's search results by updating the title to match the phrasing customers actually used when searching. I asked support to tag tickets related to that flow separately for the following six weeks so we could measure the actual impact rather than assume it worked. Tickets for that specific issue dropped from about fifteen a week to roughly four, and the ones that remained were different problems, not the confusion the rewrite addressed. Tying the fix to a measurable before-and-after was what made the improvement provable rather than anecdotal.

My day-to-day writing is mostly in Markdown, which I prefer for technical docs because it's lightweight, works well with version control, and keeps formatting from getting in the way of the actual content. I've worked with docs-as-code setups where documentation lives in Git alongside the product codebase, changes go through pull requests, and a static site generator, I've used both Docusaurus and MkDocs, builds the published site from the source files. For larger, more structured documentation sets I've used Confluence, which works well for internal knowledge bases but is less suited to versioned, publicly published docs in my experience. For API documentation specifically, I work from OpenAPI or Swagger specs where possible, since generating reference content directly from the spec keeps it accurate as the API changes, rather than hand-maintaining a document that can drift. I use Vale for automated linting against our style guide, and Snagit for annotated screenshots when a visual walkthrough is more useful than text alone. I'm comfortable picking up a new toolchain quickly: what matters more to me than any specific tool is understanding the underlying workflow, source control, review process, and publishing pipeline, because that structure transfers across tools.

I'd start with a getting-started guide that takes a developer from zero to their first successful API call in the fewest possible steps: authentication, a single example request, and the expected response, nothing else. Developers evaluating whether to use an API often decide within the first few minutes based on how quickly they can get something working, so that first page carries a lot of weight. After that I'd structure the reference documentation by resource or endpoint, with consistent sections for each one: description, required parameters, a request example, a response example, and common error codes with what causes them. I'd keep the reference content as close to auto-generated from the OpenAPI spec as possible, so it doesn't drift from the actual API behaviour. Alongside the reference, I'd add task-based guides for common use cases that combine multiple endpoints, since a developer building a real integration usually needs to know how several calls work together, not just each one in isolation. I'd also include a changelog and a clear versioning policy, since API consumers need to know what changed and whether it will break their existing integration before they update anything.

Wherever I can, I follow every instruction myself exactly as written, using a clean test environment rather than one where I already have things configured from previous testing, because a clean environment catches missing setup steps that an already-configured one hides. For anything involving code samples, I actually run the code rather than trusting that it looks correct, since a single typo in a sample can block a reader for much longer than it took me to make the mistake. For more complex technical claims I can't verify hands-on, like details of an internal architecture, I ask the engineer who built it to review the specific paragraph rather than the whole document, because a focused review request gets a more careful check than 'can you look this over' on a long page. I keep a short list of open questions during drafting rather than guessing and hoping I got it right, and I don't publish until those are resolved. After publishing, I treat support tickets and reader feedback as an ongoing accuracy check: if multiple people get stuck at the same step, that's often a sign the instructions were unclear or something changed in the product since the doc was written, not that the readers made a mistake.