Learn technical writing: explain complex things clearly
This curriculum takes a beginner from the core principles of clear writing all the way to professional-grade technical documentation for developers and users. Each stage builds on the last: first establishing writing fundamentals, then introducing technical writing craft and tools, and finally covering advanced documentation strategy, API writing, and career growth in the docs-as-a-product era.
Foundations: Writing with Clarity
BeginnerBuild the essential writing instincts — clarity, concision, and reader-first thinking — that underpin all good technical communication.
▸ Study plan for this stage
Pace: 4–5 weeks total: Weeks 1–3 cover "On Writing Well" (~20–25 pages/day, reading actively with a pencil in hand); Weeks 4–5 cover "The Elements of Style" (read the full book once quickly in 2–3 days, then re-read slowly rule-by-rule, spending ~2–3 days per chapter to study and apply each principle). Bo
- Clutter is the enemy: every word must earn its place (Zinsser's core argument — strip every sentence to its cleanest components)
- Reader-first thinking: always ask 'Who is my reader, and what do they need from this sentence?' before writing or revising
- The transaction between writer and reader: writing is an act of communication, not self-expression — the reader's comprehension is the only measure of success (Zinsser, Ch. 1–2)
- Simplicity and brevity as virtues: prefer the short word, the short sentence, and the short paragraph (reinforced by both Zinsser and Strunk)
- Omit needless words: Strunk's most famous rule (Rule 17) — every revision pass should ask 'what can I cut without losing meaning?'
- Active voice over passive voice: Strunk Rule 14 — active constructions are clearer, more direct, and more energetic
- Use definite, specific, concrete language: Strunk Rule 16 — vague abstractions weaken technical writing; precise nouns and verbs do the work
- Consistent style and usage rules: punctuation, grammar, and word-choice conventions (Strunk Part I) are not pedantry — they reduce cognitive load for the reader
- In your own words, what does Zinsser mean by 'clutter,' and what are three specific forms it takes in everyday writing?
- Zinsser argues that writers must think about 'the transaction' with the reader. What does this mean, and how should it change the way you approach a first draft versus a revision?
- Strunk's Rule 17 says 'Omit needless words.' Find a 3-sentence passage you wrote recently and apply this rule — what did you cut, and did the meaning survive intact?
- Why do both Zinsser and Strunk favor active voice? Describe a situation where passive voice might still be appropriate in technical writing.
- Strunk emphasizes using specific, concrete language (Rule 16). How does this principle apply differently in technical writing compared to general nonfiction?
- After reading both books, how would you define 'clarity' in writing? What are the two or three most powerful levers you now have to achieve it?
- The Clutter Audit (Zinsser-inspired): Take any email, report, or document you wrote in the past month. Print it out and cross out every word that does not add meaning — adverbs, redundant phrases ('in order to' → 'to'), throat-clearing openers. Aim to cut 20–30% of the word count without losing a single idea.
- The Strunk 17 Drill: Write a 200-word explanation of something you know well (a hobby, a workflow, a tool). Then apply Rule 17 ruthlessly — rewrite it targeting 130 words or fewer. Read both versions aloud and note which is easier to follow.
- Active Voice Conversion: Find 10 passive-voice sentences in any technical document (a manual, a wiki, a report). Rewrite each in active voice. For each one, decide: is the active version genuinely better, or is there a reason the passive was used?
- Reader Persona Exercise (Zinsser Ch. 2): Before writing your next piece — even a short email — write one sentence at the top of your draft that names your reader and states exactly what they need to walk away knowing. Revise the piece with only that sentence as your guide.
- The Elements of Style Rule-a-Day Journal: Over 5 days, pick one Strunk rule per day (e.g., Rule 13, 14, 15, 16, 17). Write 3 original sentences that violate the rule, then rewrite each sentence to follow it. Reflect in 2–3 sentences on what changed.
- Before/After Revision Portfolio: Collect 3 short pieces of writing (yours or publicly available technical docs). Apply the combined lessons of both books — cut clutter, activate voice, sharpen nouns and verbs, follow Strunk's usage rules. Save the before and after versions side by side as a personal reference artifact.
Next up: Mastering clarity and concision at the sentence and paragraph level creates the essential foundation for the next stage, where these instincts will be scaled up to structuring complete technical documents — organizing information logically, guiding readers through complex material, and choosing the right format for the right audience.
The single best primer on clear, non-fiction prose. It trains the beginner to strip out clutter and write for the reader — a habit that is non-negotiable in technical writing.
A compact, canonical reference for grammar and style rules. Reading it early gives you a shared vocabulary for writing quality that every technical writing resource assumes you already have.
Core Craft: Technical Writing Fundamentals
BeginnerLearn the specific principles, formats, and processes of technical writing — including how to analyze audiences, structure documents, and write procedures and reference material.
▸ Study plan for this stage
Pace: 10–13 weeks total. Week 1–4: "Developing Quality Technical Information" by Hargis (~20–25 pages/day, focusing on the quality characteristics chapters). Week 5–8: "Technical Writing Process" by Morgan (~15–20 pages/day, working through each phase of the process model deliberately). Week 9–13: "The In
- The nine quality characteristics of technical information (accuracy, clarity, completeness, concreteness, organization, retrievability, style, task orientation, and visual effectiveness) as defined by Hargis, and how to self-audit writing against them
- Audience analysis: identifying user types, their goals, experience levels, and contexts of use before writing a single word — a foundational skill emphasized across all three books
- The five-phase technical writing process from Morgan (Plan → Structure → Write → Review → Publish) and why treating writing as a repeatable, managed process rather than a one-time act is essential
- Document planning artifacts: content specifications, style guides, and information plans as described by Morgan, and how they prevent costly rework later
- Task-oriented writing: structuring content around what users need to *do* rather than what a product *is*, a principle central to Hargis's quality framework
- Procedures and reference material: the structural and stylistic differences between step-by-step procedural writing and look-up reference content, and when to use each
- The professional role of the technical writer — navigating SME relationships, review cycles, and organizational dynamics — as covered practically in Van Laan's insider perspective
- Plain language and minimalism: eliminating unnecessary content, using active voice, and writing concise sentences as a craft discipline reinforced by all three books
- According to Hargis, what are the nine quality characteristics of technical information, and can you give a concrete example of a writing failure that violates each one?
- Using Morgan's five-phase process model, how would you plan and structure a 10-page user guide for a software feature you know well — what deliverable would you produce at each phase?
- How do you conduct an audience analysis before writing a document? What specific questions should you answer about your users, and how does the answer change the document's structure and vocabulary?
- What is the difference between procedural writing and reference writing? When should you choose one format over the other, and what are the structural rules for each?
- Van Laan describes the realities of working with subject-matter experts (SMEs). What strategies does she recommend for extracting accurate information, managing review cycles, and handling conflicting feedback?
- How do the quality criteria from Hargis map onto the process phases from Morgan — at which phase should a writer be checking for clarity, completeness, and retrievability respectively?
- Quality audit exercise (Hargis): Find a real piece of technical documentation (a software manual, an API guide, an appliance manual). Score it against Hargis's nine quality characteristics, writing one paragraph of evidence per characteristic. Then rewrite one failing section to meet the standard.
- Audience analysis worksheet (all three books): Choose a tool or process you know well. Write a one-page audience analysis that identifies at least two distinct user types, their goals, prior knowledge, and likely reading environment. Then write the opening paragraph of a guide differently for each audience.
- Process plan simulation (Morgan): Before writing anything, produce the planning artifacts Morgan describes — a content specification, a document outline with section purposes, and a brief style decision log — for a hypothetical 'Getting Started' guide. Only then write the first two sections.
- Procedure writing drill (Hargis + Morgan): Write a step-by-step procedure for a familiar everyday task (e.g., setting up a Wi-Fi router or creating a Git repository). Apply task-orientation principles: one action per step, imperative mood, user-goal framing. Then rewrite it as a reference entry (a table or glossary-style format) and compare the two.
- SME interview simulation (Van Laan): Role-play or actually conduct a 20-minute interview with a friend or colleague who knows something you don't. Use Van Laan's guidance to prepare structured questions in advance, take notes in real time, and produce a one-page information summary you could write from. Reflect on what was unclear and what follow-up questions you'd send.
- End-of-stage portfolio piece: Using all three books as a checklist, write a complete mini-document (400–600 words) — a short user guide or quick-reference card for any tool or process. Self-review it against Hargis's quality characteristics, verify it follows Morgan's structural principles, and apply Van Laan's professional polish advice. Keep this piece; it becomes the baseline artifact for the n
Next up: Mastering these foundational principles — quality criteria, process discipline, audience analysis, and document formats — gives the reader the craft vocabulary and self-editing instincts needed to tackle more specialized or advanced topics in technical communication, such as structured authoring, API documentation, content strategy, or tools-based workflows.
IBM's definitive guide to technical documentation quality. It introduces the nine qualities of good technical information (accuracy, completeness, clarity, etc.) and is the best structured framework for a beginner to internalize.
A practical, step-by-step walkthrough of the full technical writing lifecycle — planning, drafting, reviewing, and publishing. Reads directly after Hargis to show how the quality principles are applied in a real workflow.
Covers the professional realities of the technical writer role: working with SMEs, managing reviews, and navigating a tech company. Bridges the gap between writing craft and the actual job.
Intermediate Practice: Docs for Developers and Users
IntermediateMaster the two dominant audiences in modern technical writing — software developers (APIs, SDKs) and end users — and learn the tools and workflows used in real documentation teams.
▸ Study plan for this stage
Pace: 8–10 weeks total: Weeks 1–4 for "Docs for Developers" (~25–30 pages/day), Weeks 5–7 for "Every Page Is Page One" (~20–25 pages/day), Weeks 8–10 for "Modern Technical Writing" (~15–20 pages/day, lighter but denser with tooling concepts). Plan for one reflection/exercise day per week.
- Audience-first documentation: Bhatti's framework for identifying developer needs, pain points, and mental models before writing a single word
- The eight types of developer documentation (tutorials, how-to guides, reference, conceptual docs, etc.) and when to deploy each, as outlined in Docs for Developers
- Every Page Is Page One (EPPO) philosophy: readers arrive at any page from a search engine, so every topic must be self-contained, richly linked, and context-complete
- Topic-based writing vs. book-based writing: Baker's argument that linear, chapter-dependent docs fail web readers and how to restructure content into standalone topics
- Minimalism and the 'docs-as-code' philosophy: Etter's case for treating documentation like software — version-controlled, reviewed, and continuously deployed
- Lightweight markup languages (Markdown, reStructuredText) and static site generators (Jekyll, Sphinx, Hugo) as the practical toolchain for modern doc teams
- The documentation feedback loop: integrating user analytics, GitHub issues, and developer feedback to iterate on docs the way engineers iterate on code
- Linking and navigation strategy: Baker's concept of 'thick linking' to compensate for the absence of a shared reading context across self-contained topics
- After reading Docs for Developers, can you map out the full documentation set a new public API would need — and justify the purpose of each document type?
- How does the EPPO principle from Baker change the way you would structure a help article compared to a traditional manual chapter? Give a concrete before/after example.
- What does Etter mean by 'docs as code,' and which specific practices (branching, pull requests, static sites) does he recommend adopting from software engineering?
- Baker argues that minimalism and EPPO are complementary, not contradictory. How do you reconcile writing the shortest possible topic with making it fully self-contained?
- How would you use the feedback mechanisms described in Docs for Developers (analytics, issue trackers, user interviews) to prioritize which docs to improve first?
- Across all three books, a consistent theme is that documentation must meet readers where they are. How do the recommended structures, tools, and workflows in each book serve that goal differently for developer vs. end-user audiences?
- API Doc Sprint (Bhatti-inspired): Pick any free public API (e.g., OpenWeatherMap, GitHub REST API). Write a complete getting-started tutorial, one conceptual overview, and one reference page for a single endpoint. Follow the structure templates from Docs for Developers.
- EPPO Audit (Baker-inspired): Take any three pages from an existing product's documentation site (e.g., Stripe, Twilio, or a tool you use). Score each page against Baker's EPPO checklist: Is it self-contained? Does it state its own context? Does it link richly to related topics? Write a one-page audit report with specific rewrites.
- Topic Decomposition Exercise (Baker-inspired): Take a long-form 'wall of text' help article from any software product and decompose it into discrete, self-contained EPPO topics. Draw a linking diagram showing how the topics connect to each other.
- Docs-as-Code Setup (Etter-inspired): Create a working documentation site from scratch using a static site generator (MkDocs or Hugo), write at least five pages in Markdown, host it on GitHub Pages, and configure a pull-request review workflow — mirroring the pipeline Etter describes.
- Persona & Friction Map (Bhatti-inspired): Define two personas — one developer integrating an API, one non-technical end user of the same product's UI. For each persona, write a one-page friction map identifying their top three documentation pain points, then draft the opening paragraph of a doc tailored to each.
- Cross-Book Synthesis Essay: Write a 500–700 word essay answering: 'If you were building a documentation system for a SaaS product from scratch, which principles from Bhatti, Baker, and Etter would you prioritize and why?' This forces integration of all three books before moving to the next stage.
Next up: Mastering developer and user-facing docs, self-contained topic design, and the docs-as-code toolchain here provides the practical and philosophical foundation needed to tackle advanced topics in the next stage — such as information architecture at scale, content strategy, and managing documentation across large, multi-product organizations.
The most practical and modern guide to writing developer documentation, covering API references, tutorials, and code samples. Essential reading for anyone documenting software products.
Reframes how users actually read documentation online — by landing anywhere, not linearly. This shifts how you structure topics and write self-contained content, a critical skill for web-based user docs.
A concise, opinionated guide to the docs-as-code philosophy — using lightweight markup, static site generators, and version control. Introduces the toolchain (Markdown, Git, static sites) that most modern tech writing teams use.
Advanced Strategy: Information Architecture and Content Design
ExpertThink at the system level — designing documentation sets, structuring large information architectures, and applying content strategy so that docs scale with a product.
▸ Study plan for this stage
Pace: 3–4 weeks, ~25–35 pages/day; Rosenfeld's book is dense with diagrams and frameworks, so budget extra time to sketch out IA models as you read rather than pushing through chapters passively.
- The three circles of information architecture: organization, labeling, and navigation systems working together as an integrated whole
- Organization schemes and structures: exact vs. ambiguous schemes (topical, task-based, audience-based, metaphor-driven) and hierarchical, database, and hypertext structures
- Labeling systems: controlled vocabularies, index terms, and the cognitive load that inconsistent or jargon-heavy labels place on users
- Navigation systems: embedded navigation (global, local, contextual) vs. supplemental navigation (sitemaps, indexes, guides) and how they orient users within large content sets
- Search systems: indexing strategies, search zones, query builders, and how search complements — rather than replaces — good navigation
- Thesauri, controlled vocabularies, and metadata as the invisible scaffolding that makes large documentation sets findable and consistent at scale
- The 'top-down' (business/user goals → structure) vs. 'bottom-up' (content inventory → emergent structure) approaches to designing an IA
- User research methods for IA: card sorting, tree testing, and contextual inquiry as tools for validating structural decisions before building
- How do the four components of IA — organization, labeling, navigation, and search — interact, and what breaks down in a documentation set when any one of them is neglected?
- When would you choose an audience-based organization scheme over a task-based one, and what are the trade-offs for a product that serves multiple user personas?
- What is a controlled vocabulary, and how does maintaining one prevent the 'synonym problem' from degrading search and browsability in a large doc set?
- How does Rosenfeld distinguish between embedded and supplemental navigation, and which types are most critical for technical documentation that users enter mid-site via search engines?
- What steps would you follow to conduct a content inventory and audit before redesigning the IA of an existing documentation site?
- How do top-down and bottom-up IA design approaches complement each other, and at what project phase should each be applied?
- Perform a full content inventory of a real or open-source product's documentation site (e.g., a popular GitHub project's docs): list every page, its URL, its current label, and its inferred purpose in a spreadsheet — then identify gaps, orphans, and redundancies.
- Run a DIY card-sorting exercise: write 30–40 topic labels from a documentation set onto index cards (or use a free tool like Maze or OptimalSort), ask 3–5 colleagues or friends to group them, and use the results to propose a revised top-level navigation structure.
- Redesign the navigation system of a documentation site you use regularly: sketch a global nav, a local nav, and at least two contextual navigation patterns (related links, breadcrumbs) on paper or in a wireframing tool, explicitly applying Rosenfeld's embedded vs. supplemental navigation distinction.
- Draft a small controlled vocabulary of 40–60 preferred terms for a technical domain you know well (e.g., cloud infrastructure, mobile development): include synonyms, broader terms, narrower terms, and 'use instead' redirects — then apply it to relabel an existing doc section.
- Create an IA deliverable — a visual sitemap or content model diagram — for a hypothetical new documentation set covering a product with at least three distinct user personas, explicitly annotating which organization scheme and which labeling conventions you chose and why.
- Write a one-page IA strategy memo for a documentation set that has outgrown its current structure: identify the core problem (findability, scalability, inconsistent labeling, etc.), propose a structural solution grounded in Rosenfeld's frameworks, and define the metadata schema needed to support it.
Next up: By mastering how to design and scale information architectures, the reader has built the structural foundation needed to move into advanced content strategy — where governance, content lifecycle management, and cross-team publishing workflows determine whether a well-designed IA stays healthy over time.
The canonical text on organizing and labeling large bodies of content. At this stage, technical writers need to think beyond individual pages to entire documentation systems — this book provides that mental model.
Discussion
Keep reading
Paths that share books, cover the same subject, or open a related topic.
