Technical writing fundamentals

Docs-as-code means the documentation is plain text in a version-control repository, reviewed through pull requests, built by a pipeline and deployed like software. What you get is not primarily convenience. It is that documentation becomes visible to the same mechanisms that already keep code honest: a change to a page has an author, a diff, a reviewer and a date, and a change to the code can be blocked until the page changes with it. The cost is that contribution now requires a git workflow, which excludes some of the people who have the most to say - support engineers, solutions architects, anyone whose day is not spent in a terminal. Teams that adopt it and then wonder why contributions dropped have usually not noticed that they raised the price of writing a paragraph.

A tutorial teaches a skill to someone who does not have one yet, so it is narrated, sequenced, and offers no choices - every decision is made for the reader so that the exercise finishes. Its success criterion is completion. A how-to guide serves someone who already has the skill and now has a goal, so it is titled after the goal, assumes context, and may reasonably say "configure whichever storage backend you use". Its success criterion is that the goal is reached. The confusion matters because a tutorial that starts offering alternatives stops being finishable, and a how-to guide that starts teaching fundamentals wastes the time of someone who is mid-task.

Single-sourcing is writing a piece of content once and rendering it into every place it is needed, rather than copying it. In practice that is an include or transclusion mechanism: a prerequisites block, an authentication snippet or a warning about a destructive flag lives in one file and is pulled into the six pages that need it. The benefit is that correcting it once corrects it everywhere, which is the only reliable defence against a set of pages that disagree. The cost is that an included fragment is written without knowing its surroundings, so it drifts towards a generic tone and cannot refer to the step before it.

Progressive disclosure means showing a reader only what they need to act now, and putting the rest one link or one collapsed section away. A quickstart shows the three required parameters and links the reference table with the other twenty-one. It works because the cost of a page is not its length but the number of decisions it forces, and a reader who has to evaluate options they do not understand yet stalls. The failure mode is using it to hide something load-bearing: a prerequisite or a data-loss warning behind a collapsed heading is not disclosed progressively, it is disclosed too late.

Both exist to make fifty contributors sound like one, and they do different jobs.

artefact            governs                  example entry                        enforced by
------------------  -----------------------  -----------------------------------  ------------------
Terminology list    which word names a       "Use workspace, never tenant or      text linter,
                    thing                    org"                                 review

Style guide         how sentences are        "Procedures use numbered steps       review, templates
                    built                    and the imperative"

Voice statement     register and stance      "Direct, second person, no           editor judgement
                                             exclamation marks"

Formatting rules    page mechanics           "One H1, sentence-case headings,     markdown linter
                                             no bold in body text"

Content templates   what a page must         a reference page carries a           pull-request
                    contain                  parameters table                     template

A terminology list is the highest-value document of the five and the cheapest to maintain, because inconsistent naming is the defect readers notice first: if the API calls it a workspace, the console labels it an org and the docs alternate, readers conclude these are three different objects and file a ticket asking how they relate.

The style guide is worth writing only for the rules you will actually enforce. A forty-page guide nobody reads produces no consistency and a great deal of guilt, whereas a one-page guide with eight rules and a linter produces most of the available benefit. Anything you cannot state as a checkable rule belongs in the voice statement, where it is honestly labelled as judgement.

The row that teams skip is templates, and it is the one that changes behaviour without any review effort. A contributor given an empty file writes whatever shape they last read; a contributor given a page with a Prerequisites heading already in it fills it in, which converts the most common blocking review comment into a structural default.

Topic-based authoring treats each self-contained unit of content as the authoring object rather than the page or the chapter. A topic answers one question or describes one procedure, carries no dependence on what came before it, and can be assembled into different outputs - a web page, a printed manual, an in-product help panel. The discipline it imposes is useful even without tooling: if a topic cannot be understood on its own, it will not survive being found through search, which is how most readers arrive. The cost is a set of topics with no narrative thread, so someone still has to build and maintain the assembly that gives them an order.

It is the decision about what the units of content are, how they are grouped, how a reader moves between them, and what each page is allowed to contain. That covers the navigation tree, the naming of sections, the boundary rules that keep reference out of tutorials, and the entry points a reader lands on. It is architecture in the real sense because it is expensive to change later: URLs get linked, search engines index them, and support macros point at them, so a restructure means redirects and a period of broken bookmarks. Getting the top two levels roughly right early is worth more than perfecting any single page.

A technical writer's output is content: they interview engineers, learn the system, decide what a reader needs and write it. A documentation engineer's output is the machinery: the site generator, the CI checks, the reference generation from a spec, the link checker, the versioning scheme, the search index. Small teams combine the two roles and the combination is common enough that job titles are unreliable. The distinction matters in an interview because the two are scored differently - one round probes whether you can restructure a bloated page, the other probes whether you can make a broken build fail loudly, and turning up prepared for only one of them is a common mistake.