Technical Writing

What this area actually covers

Three activities, only one of which is writing sentences. The first is finding out what is true, which in practice means reading code you did not write, interviewing the person who did, and running the procedure yourself on a machine that has none of your convenient leftovers on it. The second is deciding what a reader needs and where it goes - which page, which position on the page, which mode of writing, what gets left out. The third is producing the prose, and it is the smallest of the three by effort and the least decisive in an interview.

That ordering is unintuitive enough to be worth stating plainly, because it is the thing candidates get wrong about the discipline. A page can be grammatical, consistent, well-formatted and accurate and still fail every reader who opens it, because the sentence they needed was in paragraph six and they had already run the command in paragraph two. Almost every serious documentation defect is of that shape: correct information positioned where nobody reaches it, or lookup material buried in narrative, or a warning that arrives after the action it warns about. Fixing those is structural work. Nothing about it is fixed by better sentences.

The area also covers the machinery, because in modern practice documentation is built and deployed rather than published. That means a repository, a static site generator, a continuous integration pipeline with linting and link checking and preview deploys, a versioning scheme for products with supported old releases, and - where an API is involved - reference pages generated from a specification rather than typed by hand. Some organisations split this into a separate role and some expect one person to do both, so the boundary is worth understanding even if you never intend to own the build.

What gets wrongly bundled in: marketing copy, which is written to persuade rather than to enable and is judged by conversion rather than by whether anyone succeeded; user-interface copy, which is a related craft with different constraints, since a button label has no room for a caveat; training and course design, which assumes a captive learner rather than someone mid-task at half-past-one in the morning; and knowledge-base work for a support organisation, which is genuinely adjacent but is optimised for deflecting a ticket rather than for teaching a system.

There is one more boundary that decides how a whole interview goes. Technical writing is not transcription. A writer who takes what an engineer says and renders it in clean prose has produced something, but they have not done the part the job exists for, which is to notice that the explanation assumes a credential the reader does not have, that the second step is really three, and that the interesting error case was mentioned in passing and belongs in a table. Candidates who describe their process as "I interview the engineer and write it up" sound like transcribers. Candidates who describe what they push back on sound like writers.

The subsection underneath: docs as code

This section currently has one subsection, and the concentration is deliberate rather than an accident of coverage. Almost everything a documentation interview asks that is specific to software documentation rather than to writing in general lives in this one practice, so it gets a subsection of its own rather than being scattered across a general writing area.

Docs as Code is the practice of treating documentation as a software artefact. The pages are Markdown or a similar plain-text format, they live in a git repository, a change to them arrives as a pull request with an author and a diff and a reviewer, a pipeline lints and builds and link-checks them, and the site deploys the same way an application does. Stated like that it sounds like a tooling preference. It is not: it changes who can contribute, what can be enforced automatically, and whether a documentation change can be made a condition of a code change.

It exists as a separate thing because it is the point where documentation stops being a matter of individual diligence. A style rule that lives in a wiki page is an opinion a reviewer has to assert; the same rule in a linter is a fact about the repository, and moving it changes the social meaning of the enforcement as much as the mechanics. A reference page typed into a content-management system is a second copy of the interface that drifts silently from the first; the same page generated from a specification, with a check that fails when the specification and the running service disagree, cannot drift the same way. In both cases the improvement is structural, and that is the argument the practice rests on.

A reader who opens this subsection finds the questions an interviewer asks to establish whether you have actually worked this way, rather than read about it. How you keep an API reference in step with an API that changes weekly, which is mostly a question about what you generate and what you write and where the seam between them falls. How you review a documentation pull request from a competent engineer who is a weak writer, which is only partly a writing question and mostly a question about which findings you are willing to block on and which you leave alone to keep the contributions coming. And how you structure a documentation set for readers who arrive with conflicting intents - the newcomer who needs a finishable path and the on-call engineer who needs one enum value - which is where information architecture stops being abstract.

The three question pages there are deliberately scenario-shaped, because that is how this material is examined. Nobody asks you to define docs-as-code. They describe a mess and watch what you reach for first.

Where it sits in a real system

Documentation sits at the junction of a change and a reader, and the interesting structural question is how far apart those two are. In an organisation that has not thought about it, a behaviour changes on Monday, someone remembers the documentation in the following quarter, and the reader in between is served a page that is confidently wrong. In one that has, the page changes in the same pull request as the behaviour, because the two files are in the same repository and a check notices when one moves without the other.

flowchart TD
    A[Engineer changes behaviour] --> B[Same pull request<br/>touches docs]
    B --> C[Pipeline lints<br/>and builds]
    C --> D[Reference regenerated<br/>from the specification]
    D --> E[Preview deploy<br/>reviewer reads the page]
    E --> F[Published site]
    F --> G[Reader mid-task]
    G --> H[Support ticket<br/>when the page failed]
    H --> B

The edge worth staring at is the last one, from the support ticket back to the pull request. Most documentation sets have every arrow in that loop except that one, which is why they grow: each ticket becomes a request to write something new, and nobody asks whether the answer was already written and simply not found. Closing that arrow is the single highest-value change most documentation organisations could make, and it costs a habit in the support team rather than a tool.

The other thing to read from the diagram is where the human review sits. It is after the mechanical checks and after the preview deploy, not before them. That ordering is the whole design goal of a documentation pipeline: a review comment is the most expensive way to enforce a rule a script could enforce, and it is also the one that makes a contributor feel judged. By the time a person looks, the heading levels are already right and the broken relative links are already caught, so the reviewer's attention goes to the things only a person can see.

Downstream, the documentation set is load-bearing for parts of the business that never appear in a docs team's remit. Support macros link pages. Error messages carry URLs. Sales engineers send a getting-started guide to prove an integration is feasible. Procurement questionnaires ask for the security page. This is why URLs are a public interface and why moving a page without leaving the old path resolvable breaks things silently: the links are in places the documentation team cannot see and cannot update.

The four modes, and why the split is structural

The framework worth knowing by name is Diátaxis, which separates documentation by what the reader is doing rather than by subject. It names four modes - tutorial, how-to guide, reference and explanation - and derives them from two axes: whether the reader is acting or trying to understand, and whether they are at study or at work.

The reason this is more than a filing scheme is the last column. Each mode is defined as much by what it excludes as by what it holds, and the exclusions are the instructions that are genuinely hard to obey. Taking a true and important production caveat out of a tutorial feels like removing value from the page. It is the change that makes the tutorial finishable, because a reader with no model of the system cannot evaluate a caveat and will stall on it. Similarly, moving three paragraphs of design rationale off a reference page feels like a loss until you picture the person who is looking for a parameter default while something is broken.

The boundary teams get wrong most often is reference against explanation, because both answer the question "how does this work". The test that resolves it is not whether the material is conceptual but whether the reader needs it while working. A sentence saying that identifiers sort by creation time is conceptual and belongs in reference, because someone is looking at one right now and wondering.

flowchart TD
    P[A paragraph to place] --> A{Does it tell the<br/>reader to do something}
    A -->|Yes| B{Could a newcomer follow it<br/>from start to finish}
    A -->|No| C{Does the reader need it<br/>while working}
    B -->|Yes| T[Tutorial step]
    B -->|No| H[How-to guide]
    C -->|Yes| F[Reference entry]
    C -->|No| E[Explanation]

Follow the left branch first, because "does this contain an instruction" is the one question a contributor can answer about their own paragraph without knowing the information architecture at all. What the tree cannot decide is whether the paragraph should exist, and that is the more common problem: someone who has just debugged something painful wants to write the story of the debugging, and usually two sentences of it belong in reference as an error description while the rest belongs in a postmortem.

Diátaxis is one answer rather than the answer, and saying so in an interview is a better signal than reciting it. It suits a product with a real learning curve and a large surface. A single-endpoint internal service does not need four sections, and imposing them produces four thin pages where one good one would have done.

Who does this work

The people who write are technical writers, and in developer-facing companies the title is often documentation engineer or developer documentation lead. A day is less writing than the two activities around it. A recurring shape: an hour extracting a system from an engineer who has ten minutes of patience, an hour running the procedure they described on a clean environment and discovering that step two assumes a permission nobody mentioned, an hour reshaping a page that has grown past what a reader will scroll, and a stretch of pull-request review where the real decision is which comments not to leave.

The people who build the machinery are documentation engineers proper, where the role is separated, or platform engineers where it is not. Their output is not content: it is the site generator, the reference generation from a specification, the link checker, the versioning scheme, the search index, and the checks that make a documentation failure visible in a build rather than in a ticket three weeks later. Small teams combine both roles in one person, which makes job titles an unreliable guide to what an interview will actually probe.

Then there are the people who contribute without owning: engineers who write the first draft of their own feature, support engineers who know exactly which sentence is missing because they have typed it into forty tickets, solutions architects who have watched customers fail at the same step. These are the highest-value contributors and the most easily lost, because docs-as-code raises the price of writing a paragraph. A team that adopts a git workflow and then wonders why contributions dried up has usually not noticed what it charged.

The working loop between a writer and a subject-matter expert is worth seeing as a sequence, because the order is what makes engineers agree to take part.

sequenceDiagram
    participant W as Writer
    participant E as Engineer
    participant C as Clean environment
    participant R as Reviewer
    W->>E: 30 minutes, recorded, questions prepared
    E-->>W: how it works, and what breaks
    W->>C: run every step as described
    C-->>W: step 2 assumes a permission
    W->>E: correctness check on a finished draft
    E-->>W: two corrections, no rewriting asked
    W->>R: pull request with the transcript attached

The asymmetry is the point. The engineer is asked for thirty minutes and a bounded correctness check, never for a draft, because a request for a draft becomes a three-week wait and then an apology. Everything between those two exchanges is the writer's work, and the clean environment is where the finding that mattered came from.

Adjacent and distinct: developer advocates, whose output is reach rather than reference and who are measured on adoption; content designers, who own in-product wording; and localisation specialists, whose constraints reach back into how you write the source - short sentences, consistent terminology, no idiom, because the same discipline that helps a translator helps the many readers who will run your page through machine translation whether you planned for it or not.

Demand, adoption and how that is changing

Demand is steady rather than booming, and the honest version of why is that several forces are pulling in different directions at once.

Pulling up: every organisation selling an API is selling its documentation, because an integrator who cannot get a first call working evaluates a competitor, and nobody phones a salesperson first. Regulated industries need documentation as evidence rather than as a courtesy, which makes it a funded obligation rather than a discretionary nicety. And the volume of software surface per engineer keeps rising, so there is more to document than there was.

Pulling down: the drafting share of the work has become cheap. Producing a first pass over a reference page, restructuring a long document, summarising a design document, tightening prose - generative tooling does all of that at a quality that would have been an acceptable junior draft, and a meaningful part of what entry-level documentation work used to consist of was exactly that. It would be dishonest to pretend otherwise, and a candidate who claims nothing has changed reads as someone who has not been paying attention.

What that leaves is a shift in which parts of the job are scarce rather than a simple contraction. Two things did not get cheaper. Knowing whether a page is true, which requires running the procedure on a clean environment and reading the code, and cannot be done by anything that has only read the previous version of the documentation. And deciding what a reader needs, which requires knowing who the reader is, what they arrived from, and what they will do next. The volume of plausible, fluent, unverified documentation is rising, and that makes verification and structural judgement more valuable rather than less.

The visible consequence in hiring is a compression of the ladder. Work that used to be given to a junior writer to produce is increasingly given to a tool and then reviewed, which means the roles that remain skew towards people who can own an area, argue with an engineer, and be trusted to say that a page is correct. That is harder on people entering the field than on people already in it, and it is worth naming rather than glossing.

One further shift is structural rather than technological. Documentation has moved into engineering organisations - into the repository, the pull request and the pipeline - and away from separate publications teams. The consequence is that a writer is now judged partly on how well they operate inside an engineering workflow, which is why a documentation interview asks about git and continuous integration at all.

What makes it hard

The hardest part is that you have to be wrong in a specific way to find the defects. You know the system, so you cannot read the page as someone who does not - and the defects that matter are exactly the ones invisible to a reader who already knows the answer. The missing prerequisite is invisible because you have it. The ambiguous step is unambiguous because you know which of the two readings is correct. The only reliable defences are mechanical: run the procedure on an environment with nothing on it, and watch a real person from the intended audience attempt it without helping them.

Second, verification is unglamorous and is the thing under time pressure. It is much faster to write a plausible page from a conversation than to run what the conversation described, and nothing in a review reliably catches the difference, because a well-written untested procedure reads exactly like a well-written tested one. This is where a documentation set quietly rots: not through bad prose but through accumulated unverified accuracy.

Third, the social problem is real and is underestimated by candidates. The scarcest input to a documentation set is contributions from people who understand the system, and a review that reads as a rejection reduces that supply. An engineer who receives twenty-two comments of which eighteen are style preferences does not conclude that they should write better; they conclude that writing belongs to the writer, and next time the behaviour changes nothing gets written at all. You traded an awkward page for an absent one. Judging which findings to raise and which to let go is a skill that takes years and looks like laziness from outside.

Fourth, there is no equivalent of a test suite for most of what you produce. Code samples can be extracted from files that compile. Reference shape can be generated from a specification. Links can be checked. Everything else - prerequisites, sequencing, whether an explanation actually explains, whether the title uses the reader's words - is invisible to every check you own, which means staleness is silent and the only signals are indirect: a ticket whose answer was already written down, a search with impressions and no clicks, a tutorial where readers stop at the same step.

Finally, the work is judged on an outcome you rarely observe. A page that works produces silence. A page that fails produces a ticket that arrives in a different team's queue, phrased as a product complaint. Building the feedback path that connects the two is most of what senior work in this area consists of, and it is not writing.

Why study it

Study it if you want to be the person who knows how a system actually behaves rather than how it was described in a design document, because that is the side-effect of doing this work honestly - you run everything, and you find the gaps. It also travels: the ability to take a tangled explanation from an expert and turn it into something a stranger can act on is valuable in developer relations, in solutions engineering, in product management, and in any engineering role where design documents and postmortems are read by people who were not in the room.

Study it if you are already an engineer and want a lever that is cheap to pull. An engineer who writes a genuinely usable reference page for their own service is doing something visibly rare, and the skill transfers directly into design documents, incident write-ups and pull-request descriptions, which are the artefacts your work is judged through when you are not in the room.

Do not study it expecting a writing job that is mostly writing. If what you want is prose craft, this is not the fastest route: most of the day is investigation, structural decisions and negotiation, and the sentences are the part that goes quickest. Do not enter it expecting the drafting skill alone to be a career - that is the part that has become cheap. And if your interest is in persuading rather than enabling, marketing content and developer advocacy are honestly better fits, with different measures of success.

Your first hour

Pick a product you do not know, with public documentation and a free tier. Open its quickstart on a machine that has none of its tooling installed, and follow it literally - no filling in gaps from experience, no using a credential you happen to have already. Keep a running note of every place you had to stop.

Log while following the quickstart
---------------------------------------------------------------
step  what the page said              what actually happened
1     "install the CLI"               worked
2     "authenticate"                  needed an org id the page
                                      never told me where to find
3     "create a workspace"            worked
4     "run the sample"                failed: sample uses a region
                                      the free tier does not offer
5     "verify in the console"         no such menu item; renamed

Then write, for the worst finding:
  Mode        which of the four this belongs in
  Placement   where on the page it has to appear, and before what
  Repair      the smallest edit that stops the next reader failing
  Evidence    the exact error text a reader will see

Then produce one artefact: a single page of Markdown proposing the fix. Give it a prerequisites block whose entries are checkable - not "familiarity with the platform" but "an organisation id, which you find under Settings" - a numbered procedure with one action per step, and one error documented with what happened and what the reader should do about it. Keep it short. The point is not volume; it is that you have done the loop the job is made of: follow, fail, diagnose structurally, and repair in a way someone could merge.

If you want a second half-hour, take any API you have used, open its reference page for one endpoint, and write down which parts of that page could have been generated from a specification and which parts could only have been written by a person. The line you draw is the single most useful thing to have thought about before a developer-documentation interview, because most of the interesting questions in this area are about where that seam falls and what falls through it.

What this is not

It is not copy-editing. A review that catches every comma and misses that step four fails on a clean environment has done the less valuable half of the job. The finding that matters is the one that changes what a reader does.

It is not a role for people who dislike technical detail. You will read source code, inspect payloads, run commands and argue about what a status code means. Writers who avoid that produce pages that are fluent and vague, which readers learn to distrust faster than they distrust awkward prose.

It is not the same as knowledge management or a support knowledge base. Those are optimised to resolve a contact, are often written after the fact by whoever answered, and are measured on deflection. Useful, adjacent, and a different craft with a different unit of work.

It is not the same as developer advocacy, though the two overlap and people move between them. Advocacy is measured on reach and adoption and is allowed to be persuasive; documentation is measured on whether someone succeeded and is not. A conference talk and a reference page fail in completely different ways.

Nor is it a writing-only job in a docs-as-code organisation. You will open pull requests, read continuous integration output, resolve merge conflicts and occasionally fix the build. Candidates who present this as beneath the writing role are describing a job that has mostly stopped existing in software companies.

And it is not made obsolete by generative tooling, though the shape of it has changed and anyone claiming otherwise in either direction is not worth listening to. What became cheap is producing text. What did not become cheap is knowing whether the text is true and whether it is in the place the reader will reach it.

The most common serious documentation defect is not bad writing. It is correct information positioned somewhere the reader never gets to.