Technical documentation transfers hard-won knowledge from the people who built a\nthing to the people who must use, operate, or extend it — without those two\ngroups ever meeting. A technical writer stands in for the absent expert: they\nanticipate the question a stranger will have at 2 a.m. with a broken build, and\nhave already answered it, in the fewest words, at the moment they need it. The\ncraft exists because the people who understand a system best are usually the\nworst at explaining it — they have forgotten what it was like not to know.
\n","wordCount":97},{"heading":"Core Mission","id":"core-mission","markdown":"Get a specific reader from where they are to where they want to be, correctly\nand as fast as possible, so they can stop reading and get back to their work.","html":"Get a specific reader from where they are to where they want to be, correctly\nand as fast as possible, so they can stop reading and get back to their work.
\n","wordCount":31},{"heading":"Primary Responsibilities","id":"primary-responsibilities","markdown":"The visible output is prose, diagrams, and reference tables, but the actual work\nis reducing the reader's cognitive load and the support team's ticket queue. A\ntechnical writer spends their days: interviewing engineers and PMs to extract\nknowledge that lives only in heads; analyzing who the audience actually is and\nwhat they're trying to accomplish; structuring information into findable,\nscannable topics; writing and ruthlessly cutting; maintaining reference material\n(API docs, CLI flags, config options) that must be exactly right; testing every\nprocedure by actually doing it; keeping content accurate as the product changes\nunderneath it; and owning the information architecture — the taxonomy,\nnavigation, and search that decide whether anyone can find the page at all.\nUnderneath all of it is advocacy: the writer is often the first honest user the\nproduct ever meets.","html":"The visible output is prose, diagrams, and reference tables, but the actual work\nis reducing the reader's cognitive load and the support team's ticket queue. A\ntechnical writer spends their days: interviewing engineers and PMs to extract\nknowledge that lives only in heads; analyzing who the audience actually is and\nwhat they're trying to accomplish; structuring information into findable,\nscannable topics; writing and ruthlessly cutting; maintaining reference material\n(API docs, CLI flags, config options) that must be exactly right; testing every\nprocedure by actually doing it; keeping content accurate as the product changes\nunderneath it; and owning the information architecture — the taxonomy,\nnavigation, and search that decide whether anyone can find the page at all.\nUnderneath all of it is advocacy: the writer is often the first honest user the\nproduct ever meets.
\n","wordCount":133},{"heading":"Guiding Principles","id":"guiding-principles","markdown":"- **Write for the task, not the feature.** Readers arrive with a goal (\"deploy\n this\"), not curiosity about your dropdown menu. Document the job to be done.\n- **Minimalism is the discipline.** Following John Carroll's minimalist\n doctrine: support action immediately, cut everything that doesn't help the\n reader act, and trust the reader to think. Every sentence must earn its place.\n- **Fight the curse of knowledge.** The expert's worst instinct is to assume\n shared context. Name the prerequisite, define the term, show the first step.\n- **Findable beats complete.** A perfect answer no one can locate is worthless.\n Information architecture and search are features, not afterthoughts.\n- **Docs as code.** Treat documentation like software: version it, review it in\n pull requests, build it in CI, test it, and ship it with the product.\n- **Show, then tell.** A working example outperforms three paragraphs of\n explanation. Lead with the code, the screenshot, the command.","html":"A technical writer sits at the seam between engineering, product, support, and\nthe user. They extract from engineers and PMs (who hold the facts and roadmap),\npartner with UX writers and designers (who own in-product text), feed and are fed\nby support (the richest source of real reader pain), and increasingly review\ndeveloper-authored docs. The recurring friction is the late hand-off: writers\nbrought in after a feature is built can only document what shipped, not improve\nit. The strongest writers embed early enough to file usability bugs while they're\nstill cheap, and treat the engineer's time as the scarce resource it is —\narriving at interviews with specific questions, not "tell me how it works."
\n","wordCount":117},{"heading":"Ethics","id":"ethics","markdown":"Documentation is where a company's claims meet a user's reality, which makes\nhonesty the core duty. Writers must document what the product actually does, not\nwhat marketing wishes it did; surface real limitations, risks, and destructive\noperations clearly (the `rm -rf`, the irreversible migration, the data-loss\nwarning); and refuse to bury safety-critical caveats for the sake of a clean\nflow. Accessibility is an ethical obligation, not a nicety: alt text, readable\ncontrast, structure that works with screen readers, and plain language for\nnon-native speakers. When docs are used to paper over a genuinely unsafe or\ndeceptive product behavior, the right move is to escalate the product problem,\nnot to write a more persuasive workaround.","html":"Documentation is where a company's claims meet a user's reality, which makes\nhonesty the core duty. Writers must document what the product actually does, not\nwhat marketing wishes it did; surface real limitations, risks, and destructive\noperations clearly (the rm -rf, the irreversible migration, the data-loss\nwarning); and refuse to bury safety-critical caveats for the sake of a clean\nflow. Accessibility is an ethical obligation, not a nicety: alt text, readable\ncontrast, structure that works with screen readers, and plain language for\nnon-native speakers. When docs are used to paper over a genuinely unsafe or\ndeceptive product behavior, the right move is to escalate the product problem,\nnot to write a more persuasive workaround.
The API that shipped with a one-line changelog. Engineering ships a new\n/transactions endpoint with a stub in the OpenAPI spec and no prose. The writer\nfirst asks who calls this — internal teams or external partners? It's external,\nso trust and exactness matter most. They generate the reference table from the\nOpenAPI spec so it can never drift from the code, then write the pieces a\ngenerator can't: a "common errors" section from the support backlog, an\nauthentication walkthrough, and a curl example they execute against staging. When\nthe call returns a 422 the engineer didn't mention, that becomes both a doc\ncaveat and a bug report. The reference stays generated; only the judgment is\nhand-written.
Support tickets keep asking the same question. Analytics show 200 tickets a\nmonth asking "why did my webhook stop firing?" The naive response is to write a\nlonger webhooks page. The expert reads the actual tickets and finds the root\ncause: webhooks silently disable after repeated 500s, and nothing tells the user.\nThis is a product problem wearing a docs costume. The writer files an engineering\nticket for an in-product notification, and meanwhile ships a short,\nsearch-optimized topic titled exactly as users phrase it ("Webhook stopped\nfiring") with the inverted pyramid: cause first, fix second, prevention last.\nTicket volume is the success metric, not page views.
\nInheriting a 400-page legacy doc set. A writer takes over docs spanning three\nproduct versions in one undifferentiated pile, last reviewed two years ago.\nRather than rewrite everything, they instrument first — search logs and analytics\nto find the 20 pages serving 80% of traffic. They audit those against the current\nproduct, fix the high-traffic lies, and add version banners. They apply Diátaxis\nto the mess, splitting tangled "everything about X" pages into a concept, a task,\nand a reference; low-traffic stale pages get archived, not maintained. Trust is\nrebuilt where readers actually land, one corrected page at a time.
\n","wordCount":328},{"heading":"Related Occupations","id":"related-occupations","markdown":"A technical writer shares the audience-empathy and clarity instincts of several\nroles but is defined by translating expert knowledge into usable prose under the\nconstraint of a changing product. UX writers own the words inside the product;\ntechnical writers own the words around it. Instructional designers share the\nlearning-design lens but build courses rather than reference. Software engineers\nare both the source of facts and an increasingly common co-author through\ndocs-as-code. UX researchers share the discipline of studying what real users\nactually do versus what they say. Writers in the broader sense share the craft of\nprose but rarely the constraints of accuracy and versioning.","html":"A technical writer shares the audience-empathy and clarity instincts of several\nroles but is defined by translating expert knowledge into usable prose under the\nconstraint of a changing product. UX writers own the words inside the product;\ntechnical writers own the words around it. Instructional designers share the\nlearning-design lens but build courses rather than reference. Software engineers\nare both the source of facts and an increasingly common co-author through\ndocs-as-code. UX researchers share the discipline of studying what real users\nactually do versus what they say. Writers in the broader sense share the craft of\nprose but rarely the constraints of accuracy and versioning.
\n","wordCount":110},{"heading":"References","id":"references","markdown":"- *Developing Quality Technical Information* — Hargis et al. (IBM)\n- *The Nurnberg Funnel* — John M. Carroll (minimalism)\n- *Docs for Developers* — Bhatti, Corleissen, Lambourne, et al.\n- Diátaxis framework — diataxis.fr\n- *Microsoft Writing Style Guide* and *Google Developer Documentation Style Guide*\n- *Letting Go of the Words* — Janice (Ginny) Redish","html":"