Deciding what a reader needs, finding out whether it is true, and putting it where they will reach it in time. The writing is the visible part; the structural judgement and the verification are the parts that are hard to replace.
Steady demand19 min readTechnical writer, Documentation engineer, Developer documentation lead, Developer advocate, Information architect, Content designerUpdated 2026-08-10
Assumes you know: Enough command line to run a product's own quickstart, Comfort reading code you could not write, Git basics - branch, commit, pull request, Markdown, and willingness to read YAML
Overview
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.
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.
Subsection
What it is for
Docs as Code
Documentation as plain text in version control, reviewed in pull requests, built by a pipeline, and - where an API is involved - generated from a specification
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.
Loading diagram…
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.
Mode
Reader is
Their question
Must not contain
Tutorial
Acquiring a skill they lack
"Teach me to do this at all"
Choices, alternatives, production caveats
How-to guide
Applying a skill to a goal
"Get me to this specific outcome"
Teaching of fundamentals
Reference
Mid-task, looking something up
"What is the third enum value"
Narrative, rationale, history
Explanation
Building a mental model
"Why is it built like this"
Steps to follow
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.
Loading diagram…
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.
Loading diagram…
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.