# Modern Technical Writing > [!summary] Recommendation > Read [*Modern Technical Writing*](https://bookshop.org/search?keywords=Modern%20Technical%20Writing%20Andrew%20Etter) as a sharp 2016 manifesto for useful, web-first, docs-as-code practice. Keep its research-first workflow, task focus, minimum useful scope, verification, review, and frequent publishing. Replace its named toolchain and reject its dismissal of novice readers, accessibility needs, localization, privacy, and non-developer contribution paths. **Rating: 3.5/5.** ## Why this book belongs in this vault Etter’s compact argument connects technical writing, developer experience, open-source contribution, and publishing operations. It complements [[4. Archives/Book reviews/Docs for Developers]], which supplies the research and maintenance methods this book compresses or omits. It also connects to [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]], [[3. Resources/Permanent Notes/Documentation Restructure Decides Deduplication at Audit Not After]], [[3. Resources/Permanent Notes/Format Choice Is an Accessibility Control Exercised Before Remediation]], and [[3. Resources/Permanent Notes/Contribution Pathways Must Be Documented Not Left Emergent]]. The book’s durable contribution is an operating constraint: make content easy to verify, change, review, publish, find, and reuse. Its main weakness is treating the author’s preferred stack and workplace as universal. A workflow can be versioned and automated while still excluding contributors, users with disabilities, translators, regulated-document teams, and people who don’t work like software developers. --- ## Prompt 0 — retrieval, provenance, and source map ### Source record | Field | Result | |---|---| | Supplied artifact | Local PDF | | Identity | Title and author match the cover; copyright page states 2016 | | Integrity | PDF opens without encryption; Poppler reports 83 pages | | Extracted text | 10,491 words across 1,766 lines | | Source hash | `b7c2ab84b4370ad1cc79d99b839d7767b1c917fe5ad39267355ff74763810a94` | | Coverage | Every page read; representative pages visually checked | | Reader layer | No highlights, annotations, or reading-purpose statement supplied | | External layer | Current primary or field-authoritative sources used only for metadata, drift, and evidence checks | | Artifact accessibility | Text is extractable, but the PDF has no tag tree; layout extraction introduces punctuation and spacing errors | > [!warning] Layer 1 substitution > The PDF replaces Readwise as Layer 1. Every anchor below is system-selected. It records what the source says, not what the reader found important. No separate highlights file was created because the request requires one consolidated file. ### Stable anchor scheme and coverage | Anchor | PDF pages | Section | Coverage | Main function | |---|---:|---|---|---| | PDF-INTRO | 5-7 | Introduction | Read | Frames the profession as usefulness work | | PDF-BASICS | 8-10 | Basics | Read | Rejects formality, comprehensiveness, legal drafting, and print as default goals | | PDF-B01 | 11-14 | Don’t Write | Read | Makes testing and research the majority of the job | | PDF-B02 | 14-18 | Define the Audience | Read | Divides readers into users, administrators, and developers | | PDF-B03 | 19-24 | Basic Functional Documentation | Read | Defines a minimum product-documentation set | | PDF-B04 | 24-26 | Style | Read | Prefers consistency, scan structure, and restrained copyediting | | PDF-B05 | 26-27 | Catalog the Diff | Read | Makes release changes visible and scannable | | PDF-B06 | 27-28 | Build a Website | Read | Prefers updateable web content over downloaded or bundled help | | PDF-B07 | 28-30 | Help Others Write | Read | Treats the writer as curator and reviewer of contributed knowledge | | PDF-B08 | 30-32 | Publish Frequently | Read | Favors cheap builds, checks, staging, and routine release | | PDF-S01 | 33-44 | Use Lightweight Markup | Read | Compares Markdown, reStructuredText, AsciiDoc, XML, Word, and LaTeX | | PDF-S02 | 45-47 | Use Distributed Version Control | Read | Aligns documentation contribution with developer workflows | | PDF-S03 | 47-49 | Don’t Duplicate | Read | Advocates topic-based single sourcing and conditional inclusion | | PDF-S04 | 49-53 | Make Static Websites | Read | Recommends static generators, custom themes, navigation, and search | | PDF-S05 | 53-55 | Rsync | Read | Gives one deployment example for synchronizing output | | PDF-S06 | 55-58 | Metrics | Read | Uses analytics, bugs, feedback, strategy, and judgment as signals | | PDF-S07 | 58-62 | Script Your Complexity Away | Read | Moves format conversion and build complexity into scripts | | PDF-S08 | 62-63 | The Legal Problem | Read | Notes that publication may conflict with legal risk | | PDF-S09 | 63-68 | Localization | Read | Describes translation cost and gettext- or Git-based workflows | | PDF-S10 | 68-73 | Contrived Workflow | Read | Walks through a Markdown, Pandoc, Sphinx, GitHub, and server flow | | PDF-S11 | 73-78 | What About Wikis | Read | Compares wiki ease with versioning, editing, review, and maintenance limits | | PDF-FINALE | 80-81 | The Grand Finale | Read | Restates the five-part operating model | | PDF-BACK | 82-83 | Acknowledgments and legal | Read | Records source closure and copyright | ### System-selected source excerpts - “Don’t write often.” (PDF-B01) - “Writing should be the minimum possible length.” (PDF-BASICS) - “Consider everything a draft, and iterate relentlessly.” (PDF-FINALE) - “Make contribution simple.” (PDF-FINALE) These excerpts total 20 words and are the only verbatim book quotations in this note. All other source statements are paraphrases. ### Source observations - The contents page is linked and exposes the actual hierarchy clearly. - The PDF’s visual pages are readable, but the missing semantic tags weaken screen-reader navigation and reflow. - Hyperlink text and list markers sometimes disappear or split during extraction. Visual checks recovered the intended terms and lists. - The book contains no bibliography, systematic citations, index, empirical method, or documented reader study. - Footnotes often label estimates or claims as conjecture. That candor lowers the risk of mistaking them for research, but it doesn’t supply evidence. --- ## Prompt 1 — reading contract, priors, and open questions > [!note] Inferred inputs > No personal purpose, prior-belief list, constraints, or DEIB goals accompanied the PDF. I inferred an analytical purpose: decide what remains useful for technical writing, WordPress documentation, DevRel, and contributor systems in 2026. I assumed practitioner-level knowledge and a need to test accessibility and global transfer. These are system assumptions, not reader beliefs. ### Reading contract - **Decision:** Separate durable documentation principles from expired tools and narrow workplace assumptions. - **Practical use:** Build a small set of testable rules for documentation research, authoring, review, publication, and maintenance. - **Success:** Each adopted rule has a scope, current evidence, failure condition, and reversible experiment. - **Mind-changing evidence:** Current practice that makes unversioned, hard-to-review, or slow-to-publish documentation outperform a lower-friction system on accuracy, access, and maintenance. - **What the book cannot establish:** Causal business value, universal reader categories, contribution rates, the best authoring format for every team, or the cost and value of localization. - **Constraints:** One consolidated note; no reader highlights; no direct access to the author’s research notes; tool claims are ten years old. ### Prior beliefs and incentives | Area | Starting position | Confidence | Bias risk | |---|---|---:|---| | Research before drafting | Likely sound | High | Professional alignment makes confirming evidence feel familiar | | Audience-task focus | Likely sound | High | Familiarity can hide exclusion in the audience boundary | | Docs as code | Often useful, context-dependent | High | Developer-tool fluency can make Git friction invisible | | Static websites | Strong default for many public docs | Moderate | Platform preference can hide authoring and access costs | | Single sourcing | Useful with governance | Moderate | Deduplication can move complexity into conditions and reuse logic | | Analytics | Helpful as a diagnostic signal | Moderate | Quantified activity can look like user success | | Open contribution | Valuable with review and ownership | Moderate | Invitation alone can be mistaken for inclusion | | Localization | Expensive and still necessary in some contexts | High | English-first workflows can undervalue access | | PDF avoidance | Good default where print fidelity isn’t required | High | Some legal, archival, offline, and assistive uses still require documents | | Frequent publishing | Usually improves correction speed | High | Speed can outrun governance, translation, and safety checks | ### Open questions #### Definitions and mechanisms 1. Is “useful” defined by task completion, satisfaction, reduced support, business outcomes, or a combination? 2. When does minimum documentation become missing prerequisite or recovery information? 3. Does docs-as-code lower total contribution friction or shift it toward Git familiarity? 4. Which content belongs beside code, and which needs a separate lifecycle? 5. When does single sourcing reduce drift, and when does conditional content become harder to test? #### Evidence and credibility 6. What evidence supports the claimed 10% writing share? 7. Are contribution-rate estimates based on observed projects or intuition? 8. Which metrics predict successful task completion rather than page activity? 9. Does frequent publication improve correctness after review and rollback costs are counted? 10. What evidence would distinguish a good static-site workflow from a merely fashionable one? #### Scope and counterarguments 11. Which claims fail for regulated, contractual, safety-critical, or offline documentation? 12. When is a wiki’s direct editing path better than a repository workflow? 13. When does a CMS serve nontechnical contributors better without sacrificing review and history? 14. How should a team support novice users without burying experienced users in detail? 15. What fails when product code and documentation share one repository? #### Access, power, and global transfer 16. Who is excluded when Git skill becomes the price of contribution? 17. How do disabled readers change the definition of minimum useful documentation? 18. Who decides that localization costs exceed its value, and whose access is priced out? 19. How should privacy and consent constrain analytics? 20. How do low-bandwidth, mobile-only, or intermittently connected readers change format choices? ### Drift assumptions The book’s claims are fixed. Their evaluative context is live. Tool names, prices, platform support, analytics products, Markdown standardization, browser behavior, translation automation, privacy expectations, search, AI-assisted authoring, and machine readership can change within a year. The review date for these points is 2027-02-22. The core claims about verification, reader tasks, maintenance, and change review should be revisited only when contrary outcome evidence appears. --- ## Prompt 2 — inspectional reading ### Central project - **Problem:** Software documentation teams can spend heavily on formal production while serving readers poorly. - **Answer:** Learn the product and audience, write the minimum useful content, store plain-text sources in version control, automate builds, publish searchable web output often, measure behavior, and invite reviewed contribution. - **Method:** Practitioner manifesto, tool comparison, worked examples, and a contrived end-to-end workflow. - **Audience:** New and experienced software technical writers, with developers and documentation leads as secondary readers. - **Assumptions:** A software company, web access, engineering collaborators, permission to change tools, English as the source language, and documentation that can be publicly or internally hosted. - **Rhetorical modes:** Teach, persuade, advocate, warn, and provoke. ### Book map | Part | Purpose | Role in argument | Evidence | Confidence | |---|---|---|---|---:| | Introduction | Rejects production-centered professionalism | Establishes usefulness as the governing value | Career anecdote and assertion | High | | Basics | Defines research, audience, minimum scope, style, change records, web publishing, contribution, cadence | Supplies content and process principles | Examples and practitioner judgment | High | | Specifics | Recommends a 2015-era toolchain and operational workflow | Tries to make the principles executable | Tool comparisons and worked steps | High | | Grand Finale | Compresses the system into five rules | States the final thesis | Summary of prior sections | High | ### Provisional 150-word summary Andrew Etter argues that software technical writing should optimize for reader usefulness and continuous correction rather than formal production. Writers should spend most of their effort learning products, testing procedures, interviewing people, and identifying user goals. They should then create the smallest body of content that explains what a product is, where it fits, how to obtain and configure it, and how to complete a meaningful task. For production, Etter favors plain-text markup, distributed version control, topic-based reuse, static websites, automated builds, searchable output, reviewed contribution, and frequent publication. He treats analytics and bug reports as checks on editorial judgment. The book succeeds as a short operating manifesto because its research-first and iteration-first principles remain clear. Its specific stack reflects 2015, and several universal claims exceed the evidence. Its audience model, accessibility silence, localization hostility, privacy omissions, and dismissal of novice readers require repair before the system can guide current practice. ### Hotspots and reading strategy - **Read closely:** PDF-B01, PDF-B02, PDF-B03, PDF-B07, PDF-B08, PDF-S03, PDF-S06, PDF-FINALE. - **Read for historical context:** PDF-S01, PDF-S02, PDF-S04, PDF-S05, PDF-S07, PDF-S10. - **Read critically:** PDF-B02 on “helpless” readers, PDF-S08 on legal risk, PDF-S09 on localization, and PDF-S11 on wikis. - **Recommendation:** Selective deep read. The conceptual sections repay attention; the tool instructions should be compared with current systems. Change this recommendation to a skim if the reader already practices docs as code and only needs historical context. --- ## Prompt 3 — classification and terminology ### Classification - **Domain:** Software technical communication - **Subdomain:** Documentation operations and docs as code - **Genre:** Practitioner manifesto and introductory handbook - **Argument:** Prescriptive, practical, and evaluative - **Method:** Experience-based reasoning, tool comparison, examples, and workflow demonstration - **Intended use:** Change how a documentation team researches, authors, reviews, publishes, and measures work - **Comparison tradition:** Docs as code, minimalism, task-oriented writing, topic-based authoring, continuous delivery, and content operations ### Controlled vocabulary | Term | Author’s use | Operational definition for this review | Main equivocation risk | Example / counterexample | Source | |---|---|---|---|---|---| | Useful | Content readers will read and apply | Enables a defined audience to complete a task or make a sound decision | Activity can stand in for task success | Verified setup guide / polished unused brochure | PDF-INTRO | | Audience | Users, administrators, or developers with goals | People grouped by task, context, prerequisites, and access needs | Role labels hide overlap and diversity | Plugin maintainer during release / “all developers” | PDF-B02 | | Research | Product testing, source review, interviews, and questions | Evidence gathering before and during drafting | Learning can continue without a stopping rule | Reproduce install flow / read a marketing page only | PDF-B01 | | Basic functional documentation | Minimum set explaining product, context, acquisition, setup, and one end-to-end task | Smallest task-complete starting set with recovery paths | “Minimum” can erase prerequisites or edge cases | Working quickstart / feature list without outcome | PDF-B03 | | Style | Consistency and scan support with limited copyediting | Presentation rules that improve comprehension and retrieval | Consistency can be mistaken for correctness | Stable term and headings / perfectly edited wrong command | PDF-B04 | | Change log | Terse account of added, changed, removed, and upgrade-relevant behavior | Versioned release communication tied to action | Feature inventory can omit migration impact | Upgrade note / marketing announcement | PDF-B05 | | Contribution | Non-writer changes accepted through review | A documented route to propose, test, review, and own a change | An invitation can hide tooling and status barriers | Guided pull request / “edit on GitHub” with no setup | PDF-B07 | | Lightweight markup | Human-readable plain-text source syntax | Text format that supports needed semantics and diffable review | Simple syntax doesn’t guarantee simple publishing | Markdown source / opaque generated XML | PDF-S01 | | Distributed version control | Git- or Mercurial-like local history and collaboration | Versioned source with branching, review, attribution, and recovery | Tool choice can be confused with governance quality | Reviewed change / unreviewed direct push | PDF-S02 | | Single sourcing | One maintained source reused through links or inclusion | Governed reuse that reduces independent copies | Conditional variants can become hidden duplication | Shared prerequisite / copied install steps | PDF-S03 | | Static website | Prebuilt files served without runtime content generation | Publish target whose operational cost fits the team and access needs | “Static” can be mistaken for accessible, searchable, or maintenance-free | Generated docs site / inaccessible HTML bundle | PDF-S04 | | Metrics | Analytics, bugs, feedback, strategy alignment, and judgment | Signals interpreted against a stated user outcome | Page views can stand in for successful use | Search failure plus task test / traffic alone | PDF-S06 | | Publishing pipeline | Scripted transformations from source to outputs | Reproducible, observable, reversible build and deployment path | Automation can conceal brittle dependencies | CI preview and rollback / local mystery script | PDF-S07 | | Localization | Translation and adaptation for languages and locales | Governed process for language, culture, format, review, and synchronization | Cost framing can erase access and market value | Reviewed locale release / machine translation without QA | PDF-S09 | | Wiki | Browser-editable collaborative content system | Mutable knowledge system with history, permissions, review, and lifecycle rules | Product category hides large differences among implementations | Governed living handbook / abandoned page store | PDF-S11 | ### Contested language and category-error watchlist | Risk | Status | Judgment | |---|---|---| | Useful versus popular | Present | The metrics section sometimes moves too quickly from visits to value. | | Minimum versus sufficient | Present | Brevity needs a task-completion and recovery test. | | Contributor versus Git user | Present | The workflow assumes tool fluency that the contribution claim doesn’t establish. | | Technical capability versus outcome | Present | Static output and version control enable quality; they don’t produce it. | | Anecdote versus population evidence | Present | Most profession-wide claims come from the author’s workplace experience. | | Correlation versus causation | Present | Documentation traffic and support patterns can guide inquiry without proving impact. | | Description versus prescription | Present | A successful local workflow becomes a universal recommendation. | | Accessibility versus simplicity | Present by omission | Short prose and HTML help some readers but don’t establish accessible content or tooling. | | Absence of evidence versus evidence of absence | Present | No observed value in a format or audience doesn’t prove no value exists. | | Legal versus moral claims | Not developed | The legal section offers rumor and caution, not legal analysis. | --- ## Prompt 4 — claims inventory, evidence expectations, and dependencies ### Source labels - **EA:** Explicit author claim - **IA:** Implied author claim - **RI:** Review inference; never attribute this wording to Etter ### Claims inventory | ID | Source | Claim | Type | Expected evidence | Specific falsifier | Evidence in book | Anchor / question | |---|---|---|---|---|---|---|---| | C-001 | EA | Reader usefulness should govern technical-writing decisions. | Evaluative | Task outcomes and user research | A competing goal consistently produces better user outcomes without access or safety harm | Argument and examples only | PDF-INTRO / Q1 | | C-002 | EA | Writers should spend most effort testing and researching before drafting. | Prescriptive | Time studies and quality outcomes | Teams that draft earlier achieve equal accuracy and task success at lower total cost | No; 10% figure is assertion | PDF-B01 / Q6 | | C-003 | EA | Audience assumptions are necessary for focused documentation. | Methodological | Comprehension and task tests across segments | Assumption-free content performs as well without added burden | Reasoned example | PDF-B02 / Q14 | | C-004 | EA | Users, administrators, and developers form useful starting groups. | Definitional | Cross-product audience research | The categories fail to predict distinct information needs | Examples only | PDF-B02 / Q4 | | C-005 | EA | Minimum functional docs should explain purpose, ecosystem, acquisition, setup, and one end-to-end task. | Practical | Onboarding studies | A materially smaller or different set yields equal completion and confidence | Worked coffee analogy | PDF-B03 / Q2 | | C-006 | EA | Scannability and consistency matter more than rigid style compliance. | Evaluative | Retrieval and comprehension tests | Stronger style compliance improves outcomes without slowing updates | Examples only | PDF-B04 / Q1 | | C-007 | EA | Terse change logs help readers adopt and upgrade software. | Practical | Upgrade completion and error data | Users with such logs perform no better than users without them | Reasoned argument | PDF-B05 / Q8 | | C-008 | EA | Web documentation is a better default than downloaded or bundled help. | Prescriptive | Currency, access, offline, and task outcomes | Downloaded or bundled docs remain more current or accessible for the target context | Maintenance argument only | PDF-B06 / Q11 | | C-009 | EA | Writers should enable contributions and retain quality through review. | Prescriptive | Contribution and defect data | Opened contribution paths add more review cost or errors than useful knowledge | Anecdote and conjectured rate | PDF-B07 / Q16 | | C-010 | EA | Publishing should be routine, cheap, checked, and frequent. | Prescriptive | Lead time, defect, rollback, and correction data | Slower batches produce better total outcomes for the same risk class | Process argument | PDF-B08 / Q9 | | C-011 | EA | Lightweight markup lowers authoring and contribution barriers. | Causal | Completion times and contributor diversity | Target contributors succeed more often with another authoring interface | Syntax comparison only | PDF-S01 / Q3 | | C-012 | EA | Documentation should use the version-control system developers prefer. | Prescriptive | Contribution and maintenance comparison | A separate system yields higher participation and quality at lower total cost | Reasoning and examples | PDF-S02 / Q15 | | C-013 | EA | Single sourcing reduces maintenance drift. | Causal | Duplicate-defect and update data | Reuse complexity causes equal or greater inconsistency and defects | Logical argument | PDF-S03 / Q5 | | C-014 | EA | Static websites are a strong default for software documentation. | Prescriptive | Reliability, cost, access, search, and authoring data | A CMS or dynamic system outperforms it for the team’s needs | Tool comparison | PDF-S04 / Q10 | | C-015 | EA | Documentation quality needs analytics, defects, feedback, strategy, and judgment. | Methodological | Validity studies against task outcomes | The mix fails to predict or diagnose user success | Hypothetical comparison | PDF-S06 / Q8 | | C-016 | EA | Complex publishing logic should live in scripts, leaving source simple. | Design | Build reproducibility and contributor tests | The scripts become less maintainable and more exclusionary than explicit source complexity | Worked pipeline | PDF-S07 / Q3 | | C-017 | EA | Legal risk can require private source or gated output. | Cautionary | Counsel-reviewed cases and policy | Relevant counsel finds no material exposure for the context | Unsubstantiated rumor | PDF-S08 / Q11 | | C-018 | EA | Localization is costly and slows publishing. | Descriptive | Cost, cycle-time, quality, and reach data | A localization system adds little cost or delay while improving outcomes | One workflow and assertion | PDF-S09 / Q18 | | C-019 | EA | Wikis fit unversioned living documents better than versioned product docs. | Prescriptive | Comparative workflow outcomes | A governed wiki supports versioning, review, offline work, and contribution more effectively | Feature comparison | PDF-S11 / Q12 | | C-020 | RI | The durable principle is controlled change, not any named 2015 tool. | Interpretive | Cross-tool evidence over time | The principles fail when implemented outside Etter’s stack | Supported by tool drift, not stated by author | Whole book / Q10 | ### Evidence pattern The book mostly supplies logical arguments, examples, practitioner testimony, and demonstrations of tool syntax. It rarely supplies independent evidence, sample definitions, comparison groups, outcome measures, or citations. That is enough for a manifesto that generates hypotheses. It is insufficient for universal causal or numerical claims. ### Dependency graph ```mermaid flowchart TD A["C-001 Reader usefulness"] --> B["C-002 Research first"] A --> C["C-003 Audience assumptions"] B --> D["C-005 Minimum functional docs"] C --> D D --> E["C-006 Scannable content"] E --> F["C-007 Change communication"] A --> G["C-009 Reviewed contribution"] G --> H["C-011 Plain-text source"] H --> I["C-012 Version control"] I --> J["C-013 Single sourcing"] J --> K["C-016 Scripted builds"] K --> L["C-010 Frequent publishing"] L --> M["C-014 Web/static delivery"] M --> N["C-015 Measurement and iteration"] N --> A O["Warning: C-011 and C-012 can raise contributor friction"] -. weakens .-> G P["Warning: access, localization, privacy omitted"] -. constrains .-> M ``` **Load-bearing claims:** C-001, C-002, C-003, C-009, C-010, and C-015. If usefulness isn’t observable, or the authoring system excludes the people whose knowledge is needed, the workflow becomes process theater. C-020 survives the failure of any named tool and is the review’s interpretation, not the author’s sentence. --- ## Prompt 5 — quantitative rigor and confidence updates ### Policy The percentages below encode judgment; they aren’t measured probabilities. One author repeating a position across sections counts as one dependent source. A tool demonstration can show that a workflow is possible. It can’t establish that the workflow improves outcomes for all teams. | Label | Range | |---|---:| | Very low | 0-20% | | Low | 21-40% | | Uncertain | 41-60% | | Moderate | 61-75% | | High | 76-90% | | Very high | 91-100% | ### Priors and posteriors | Claim | Prior | Evidence considered | Dependence concern | Posterior | Main input | |---|---:|---|---|---:|---| | C-001 usefulness governs decisions | 90% | Book argument, W3C writing guidance, [[4. Archives/Book reviews/Docs for Developers]] | Sources share user-centered assumptions | 94% | Task usefulness is the only goal that explains why documentation exists | | C-002 research should dominate | 82% | Book workflow and vault evidence on friction logs | No time study supports the 90/10 split | 84% | Verification prevents confidently publishing wrong procedures | | C-005 minimum functional set | 72% | Worked model and later lifecycle frameworks | No direct test of the five-part set | 76% | It covers the first meaningful product journey | | C-009 reviewed contribution helps | 75% | Book, GitHub’s current contribution system, vault contribution notes | Successful open projects aren’t representative of all teams | 82% | Explicit paths plus review can capture distributed knowledge | | C-010 frequent publishing helps | 80% | Correction logic and current docs-as-code practice | High-risk content needs slower gates | 86% | Small releases shorten the life of known errors | | C-011 lightweight markup lowers barriers | 68% | Syntax comparison and docs-as-code practice | Tool-fluent communities dominate the evidence | 66% | Plain text lowers some barriers while Git raises others | | C-013 single sourcing reduces drift | 78% | Logical mechanism and vault restructure evidence | Reuse conditions can hide complexity | 81% | One maintained source removes one common drift mechanism | | C-014 static sites are a strong default | 75% | Operational properties and continued field use | Platform choice depends on contributor and content needs | 77% | Low runtime complexity remains useful, but authoring cost decides fit | | C-015 mixed metrics improve judgment | 76% | Book’s plural signal model and current documentation practice | Analytics can overrepresent visible behavior | 84% | Multiple signals can falsify editorial intuition | | C-018 localization slows publishing | 76% | Workflow complexity and current W3C translation process | Cost depends on tooling, language, cadence, and governance | 78% | Synchronizing reviewed language variants remains real work | ### Calibration warnings | Risk | Severity | Control | |---|---|---| | False precision | High | Treat percentages as ordered judgments and retain reasons | | Double-counted author examples | High | Count the book as one dependent source | | Survivorship bias in contribution stories | High | Track ignored, rejected, and abandoned contributions | | Selection effects in analytics | High | Pair traffic with task and search-failure tests | | Missing denominators | High | Reject contribution-rate and support-reduction claims without eligible populations | | Proxy measures | High | Define the user outcome before selecting a signal | | Publication bias | Moderate | Record failed workflow experiments and rollback decisions | | Tiny samples | Moderate | Use qualitative findings to generate tests, not population estimates | | Motivated estimates | Moderate | State the incentive to confirm a familiar docs-as-code model | ### Non-quantitative fallback Use five update labels where numbers would imply measurement: strongly decreases confidence, moderately decreases confidence, no meaningful update, moderately increases confidence, and strongly increases confidence. Most claims in this book belong in this qualitative system until a team runs local task and workflow tests. --- ## Prompt 6 — analytical scaffold and evidence ledger ### Argument spine 1. Documentation exists to help a defined audience do useful work. 2. Writers need product knowledge and audience evidence before they can select content. 3. The smallest task-complete documentation set reduces waste and reading burden. 4. Scan structure, verification, and release communication keep the set usable. 5. Plain-text source, version control, reuse, scripted builds, and routine publishing make change cheap. 6. Reviewed contribution expands available knowledge. 7. Analytics, defects, feedback, and judgment guide the next revision. > [!warning] Weakest link > The argument assumes Etter’s preferred authoring workflow makes contribution simpler for the people who hold needed knowledge. That is untested and often false for contributors who don’t use Git or local build tools. Repair it by choosing the lowest-friction reviewed path for each contributor group, then normalizing all accepted changes into a versioned source of truth. ### Section scaffold | Section | Thesis and evidence | Counterexample or missing condition | Relation to spine | |---|---|---|---| | Introduction | Usefulness outranks production ritual; career anecdote | Regulated form and print requirements | Sets goal | | Don’t Write | Testing and research precede prose; practitioner method | Early drafting can expose knowledge gaps | Supplies knowledge | | Define the Audience | Assumptions focus content; role taxonomy | Roles overlap; accessibility needs aren’t role-specific | Sets scope | | Basic Functional Documentation | Five questions form a minimum path; analogy | Troubleshooting, safety, recovery, and prerequisites can be central | Sets baseline | | Style | Consistency and scan structure aid use | Terminology governance and plain language need testing | Shapes content | | Catalog the Diff | Concise changes support adoption | Migration guides may need depth | Connects versions | | Build a Website | Hosted content is correctable | Offline, archival, contractual, and gated uses | Sets delivery default | | Help Others Write | Review plus contribution broadens knowledge | Tool, status, time, language, and permission barriers | Expands authorship | | Publish Frequently | Small checked releases shorten error life | Safety, translation, and legal gates may set cadence | Creates feedback speed | | Lightweight Markup | Plain text improves diffs and portability | WYSIWYG can be the accessible contributor interface | Chooses source form | | Distributed Version Control | History and developer alignment support review | Git fluency and repository policy can repel writers | Governs change | | Don’t Duplicate | Reuse limits drift | Conditional content can become untestable | Governs maintenance | | Make Static Websites | Prebuilt output lowers runtime burden | Search, personalization, permissions, feedback, and authoring still need systems | Chooses output | | Rsync | Sync removes stale output | Modern hosts provide different deployment primitives | Gives dated implementation | | Metrics | Multiple signals check intuition | Consent, privacy, bots, task success, and causality omitted | Closes feedback loop | | Script Your Complexity Away | Automate build complexity | A bus-factor-one script can become the hardest part | Supports repeatability | | Legal Problem | Publication risk may change architecture | Rumor isn’t legal evidence; counsel and jurisdiction matter | Adds constraint | | Localization | Language variants add coordination | Access and value receive too little weight | Adds global constraint poorly | | Contrived Workflow | Demonstrates an end-to-end stack | Several steps and tools have expired | Makes model concrete | | What About Wikis | Direct editing trades against versioning and control | Modern wikis vary and can add review, APIs, exports, and local sync | Compares alternative | | Grand Finale | Five rules restate the system | Accessibility and governance are missing | Closes thesis | ### Evidence ledger | Evidence | Claims | Type | Independence | Quality | Limit | |---|---|---|---|---|---| | E-BOOK | All | Practitioner argument and demonstrations | None from author | C | No research method or citations | | E-WTD | C-009-C-016 | Current field guide: Git, plain text, reviews, tests | Independent field community | B | Practice summary, not causal study | | E-CM | C-011 | CommonMark specification | Independent technical standard | A for standard existence | Doesn’t prove Markdown is best | | E-MYST | C-011, C-016 | Sphinx can use MyST Markdown | Independent current docs | A for capability | Doesn’t test user outcomes | | E-GA | C-015 | Universal Analytics sunset and GA4 replacement | Independent product owner | A for product drift | Doesn’t validate analytics as quality measure | | E-W3C | C-001, C-003, C-008 | Current accessibility standards and writing guidance | Independent standards body | A for requirements | Conformance doesn’t ensure task success | | E-GH | C-009, C-012 | Current GitHub Docs contribution workflow | Independent operating example | B | One mature open project | | E-VAULT-DOCS | C-001-C-016 | [[4. Archives/Book reviews/Docs for Developers]] | Independent authors; local secondary note | B | Existing note isn’t a fresh full-source audit | Six evidence groups are independent of Etter. E-CM, E-MYST, E-GA, and E-W3C directly tell against parts of the 2016 tool or access framing. E-WTD and E-GH support the general docs-as-code model while showing that contribution needs explicit onboarding and governance. ### Completion criteria for Prompt 7 - Full source coverage and page anchors: met. - Stable claims and falsifiers: met. - Evidence expectations and external drift checks: met. - Reader-purpose uncertainty labeled: met. - Quantitative claims scoped: met. - Accessibility and localization concerns carried into evaluation: met. --- ## Prompt 7 — x-ray analysis and fair criticism ### Strongest reconstruction **Author says:** A technical writer creates value by learning what readers need, verifying how to achieve it, writing only the content needed, and maintaining an easy path for correction and contribution. **We infer:** The preferred stack is one implementation of a controlled learning loop: observe work, encode the smallest reliable guidance, review changes, publish cheaply, inspect outcomes, and revise. This reconstruction is more systematic than the book’s presentation, but it preserves its five closing rules. ### Major claim grades | Claim | Grade | Support | Strongest objection | Repair and conclusion | |---|---|---|---|---| | C-001 usefulness governs decisions | A | Coherent purpose and external accessibility/user guidance | Safety, legal, and archival obligations can also govern | Define usefulness to include access, safety, recovery, and accountability. Adopt. | | C-002 research should dominate | B | Verification mechanism is strong | The 90/10 split is unsupported; drafting can be research | Require verified procedures and explicit unknowns, not a fixed ratio. Adopt repaired claim. | | C-003 assumptions enable focus | B | The example shows infinite-detail failure | Wrong assumptions exclude real readers | Make assumptions visible and test them with representative readers. Adopt. | | C-004 three reader groups | C | Useful initial distinctions | Roles overlap and omit operators, decision-makers, contributors, assistive-technology users, and agents | Use task and context segments. Retain only as a prompt. | | C-005 five-part baseline | B | Covers a first successful journey | Omits troubleshooting, safety, migration, and recovery | Add only what the task risk requires. Adopt as starter set. | | C-006 scan structure over rigid style | B | Strong retrieval logic and W3C alignment | Style can encode accessibility and safety rules | Prefer tested comprehension and consistency over ritual. Adopt. | | C-007 terse change logs help | B | Clear mechanism | Complex migrations need more than terse notes | Pair scan-first release notes with deep migration guidance. Adopt. | | C-008 web is the default | B | Fast correction and search are real | Offline, legal, archival, low-bandwidth, and version-pinned needs remain | Use HTML as default plus required downloadable/versioned formats. Adopt conditionally. | | C-009 reviewed contribution helps | B | Distributed knowledge and current GitHub example | Participation may cost more than it returns | Document paths, ownership, review limits, and response expectations. Test locally. | | C-010 frequent publishing helps | B | Small changes shorten correction cycles | High-risk and translated content needs gates | Publish at the fastest safe cadence for each content class. Adopt. | | C-011 lightweight markup lowers barriers | C | Raw syntax is simpler than XML | Repository and preview steps can dominate difficulty | Measure end-to-end contribution, not source syntax. Conditional. | | C-012 use developer-preferred DVCS | C | Shared tooling can aid developer edits | It can exclude writers and community experts | Keep canonical history in Git while offering alternate reviewed inputs. Adapt. | | C-013 single sourcing reduces drift | B | Direct maintenance mechanism | Conditions and reused fragments can become hard to test | Require ownership, rendered-variant tests, and escape hatches. Adopt. | | C-014 static sites are a strong default | B | Low runtime cost and portability persist | Authoring, search, permissions, and feedback systems still carry cost | Select on total workflow and access outcomes. Adopt for fitting cases. | | C-015 mixed metrics improve judgment | B | Multiple signals can challenge intuition | Metrics are proxies and can invade privacy | Start with decisions and tasks, collect the least data needed, pair with qualitative evidence. Adopt repaired claim. | | C-016 script complexity away | B | Reproducible builds protect simple source | Hidden scripts create specialist dependence | Treat scripts as product code with tests, owners, observability, and recovery. Adopt. | | C-017 legal risk may require gating | D | Plausible concern | The book cites rumor and offers no legal basis | Escalate to counsel; don’t operationalize from this source. | | C-018 localization slows publishing | C | Coordination cost is real | Cost is presented without access, revenue, safety, or trust value | Prioritize locales by need and risk; design source and cadence for translation. Adapt heavily. | | C-019 wikis fit limited cases | C | Versioning and maintenance concerns are real | Wiki products and governance vary widely | Compare requirements and current products; avoid category-level dismissal. | | C-020 durable principle exceeds stack | B | Ten years of tool drift while the operating model persists | This is the reviewer’s synthesis | Use as the primary transfer rule; never attribute it to Etter. | ### Grade distribution - A: 1 - B: 11 - C: 6 - D: 1 - F: 0 - N/A: 1 reviewer inference graded for interpretive fit The book grades well when it explains a maintenance or learning mechanism. It grades poorly when it supplies precise ratios, universal role categories, legal warnings, or category-wide judgments without evidence. No claim earns an F because most weak claims can be narrowed without breaking the central project. ### Biases and reasoning risks - **Selection bias, moderate:** The author’s experience centers software companies with engineering-oriented workflows. - **Hasty generalization, moderate:** Local tool success becomes profession-wide advice. - **Availability bias, moderate:** Painful FrameMaker, Word, wiki, and localization experiences dominate the alternatives. - **Anecdotal fallacy, high for numerical claims:** The 10% writing share and contribution-rate reasoning lack measured samples. - **False dilemma, moderate:** Several sections frame plain text versus heavyweight tools without enough hybrid cases. - **Correlation-causation risk, high in metrics:** Visits, support contacts, and product use can move together without documentation causing the movement. - **Rhetorical weakness rather than fallacy:** Insults and caricatures make disagreement sound like incompetence. The claims can still be evaluated separately. ### Counter-observations in the author’s favor - Etter admits tool advice will age and says the book has a short shelf life. - He labels some numerical claims as conjecture. - He acknowledges that shared code repositories, wikis, and static sites have tradeoffs. - He keeps personal judgment in the metrics mix rather than pretending analytics decide automatically. - He insists that commands and code should be tested before publication. ### Overall critique The book’s compression is both its strength and its limit. It names a coherent way to work in roughly 10,000 words, yet the short form leaves audience research, information architecture, accessibility, privacy, governance, localization value, maintenance ownership, and evidence validation underdeveloped. Its best transfer is operational: a documentation system should make learning, correction, review, and publication cheap. Its worst transfer is social: people who can’t use the preferred tools or follow the assumed path are treated as outside the audience rather than evidence that the system needs another entry point. --- ## Prompt 8 — context, lineage, and later developments ### Intellectual lineage ```mermaid flowchart LR A["Minimalism and task orientation"] --> E["Etter 2016"] B["Topic-based authoring and single sourcing"] --> E C["Open-source collaboration and Git"] --> E D["Continuous integration and static-site generation"] --> E E --> F["Docs-as-code field practice"] E --> G["Developer documentation lifecycle methods"] H["Accessibility, privacy, localization governance"] -. underdeveloped in book .-> E I["AI and machine-readable documentation"] -. later context .-> F ``` ### Context available in 2016 - GitHub-centered collaboration, static generators, Markdown variants, Sphinx, Jekyll, and deployment scripts were visible alternatives to desktop publishing. - CommonMark already existed as a standardization effort, which the book mentions but understates by saying Markdown had no defined standard. - WCAG 2.0 had existed since 2008. The lack of accessibility analysis was an omission in 2016, not only a later expectation. - Web analytics were common, and privacy, consent, bot filtering, and metric validity still required attention even if current rules and products differed. ### Later developments that affect evaluation - CommonMark now provides a maintained specification, so Markdown’s lack of any standard is outdated. - Sphinx can accept MyST Markdown, invalidating the contrived workflow’s premise that conversion to reStructuredText is required. - Universal Analytics stopped processing standard properties in 2023 and was shut down in 2024. The named analytics implementation has expired. - Docs as code remains a recognized practice built around plain text, Git, reviews, and automated tests. That supports the model while weakening claims of novelty. - Current accessibility guidance covers structure, link meaning, text alternatives, language metadata, clear instructions, and understandable prose. A static HTML output doesn’t meet these needs automatically. - Documentation now serves machine readers as well as people, as [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]] argues. Source format and rendered boilerplate can affect retrieval cost and authority. ### Systems model The book describes an authoring system. A current model needs five coupled systems: 1. **Knowledge:** product behavior, user tasks, support evidence, and source authority. 2. **Content:** concepts, procedures, reference, change communication, and recovery. 3. **Change:** source control, review, tests, ownership, and rollback. 4. **Delivery:** HTML, versioned/downloadable formats, search, performance, and access. 5. **Governance:** privacy, accessibility, localization, legal review, contribution policy, retention, and maintenance. Calling comparisons with current AI documentation “convergent” avoids inventing influence. The book’s authority-source and simple-source concerns resemble present agent-documentation needs, but the book doesn’t discuss language models. --- ## Prompt 9 — DEIB, multicultural transfer, accessibility, and reading level ### Inclusion strengths - The book treats non-writers as legitimate knowledge contributors. - It values searchable, scannable, task-focused content over institutional prestige. - Plain-text source can support low-cost tools, offline work, portability, and transparent change history. - It asks writers to speak with actual users and people across product, engineering, support, sales, and quality roles. These are enabling conditions. None guarantees fair participation or accessible output. ### Omission and exclusion risks - The audience model ignores disability, language, bandwidth, device, education, culture, and employment status. - The “helpless” reader passage dismisses people who need more support. It confuses one document’s scope with a judgment about a person’s capacity. - Silicon Valley, energy-drink, Burning Man, bathroom, and “jerk” imagery codes the intended workplace narrowly and can normalize exclusionary behavior. - Contributors are assumed to have Git, local tools, repository permission, unpaid time, and confidence in an engineering workflow. - Localization appears mainly as cost and delay. Readers who need another language receive no agency in the decision. - The legal discussion uses rumor and profanity in place of jurisdiction, counsel, and accountable policy. - Metrics omit consent, retention, surveillance, bot traffic, vulnerable users, and the possibility that readers avoid the site because it fails them. - The book doesn’t address race, gender, class, geography, neurodiversity, or disability directly. ### Multicultural transferability | Context | Transfer | Required repair | |---|---|---| | English-language software company | High | Update tools, privacy, accessibility, and governance | | Global open-source project | Moderate | Offer browser and non-Git paths; fund review and translation; set response expectations | | WordPress contributor documentation | High for workflow | Support varied contributor roles, low-bandwidth access, localization, and version-specific guidance | | Regulated or safety-critical product | Low to moderate | Add formal review, traceability, approved wording, retention, and release gates | | Internal enterprise knowledge | Moderate | Compare governed wiki, portal, and repository workflows rather than rejecting categories | | Mobile-only or intermittent-connectivity readers | Moderate | Provide performant pages, downloadable/versioned content, and offline-safe procedures | | Non-English-first users | Low without repair | Plan locale ownership, terminology, screenshots, change synchronization, and user review | | Community contributors without engineering tools | Low without repair | Accept structured issues, browser editing, interviews, and assisted submissions | ### Accessibility audit of the supplied PDF | Area | Finding | Effect | |---|---|---| | Semantic tags | Poppler reports `Tagged: no` | Screen-reader structure and reflow aren’t reliably encoded | | Text layer | Present and mostly extractable | Search and copy work, but spacing, punctuation, and list order degrade | | Headings | Visually clear, not semantically tagged | Sighted scan support doesn’t become programmatic navigation | | Links | Blue and underlined; some link text disappears in extraction | Visual identification is decent; assistive extraction is unreliable | | Font and contrast | Large dark serif text on white pages | Strong visual legibility for many readers | | Page size | 847.54 × 1057.37 points | Fixed layout requires zoom and horizontal navigation for some users | | Images and diagrams | Sparse; no tag structure or alternate-text evidence | Non-text meaning can be lost | | Language metadata | No useful PDF metadata reported | Assistive pronunciation can’t rely on document language metadata | ### Reading demands - **Syntactic difficulty:** Low. Sentences are conversational and sections are short. - **Reference density:** Moderate to high. Readers need context for Git, DVCS, markup languages, generators, CI, Rsync, gettext, LaTeX, and older products. - **Tone barrier:** Moderate. Profanity, ridicule, and caricature may distract or alienate readers. - **Estimated level:** Grade 8-10 for prose, with higher practical difficulty for readers outside software tooling. ### Repairs and supplementary perspectives - Pair the book with [[4. Archives/Book reviews/Docs for Developers]] for research, editing, maintenance, and measurement methods. - Use [W3C’s accessibility writing guidance](https://www.w3.org/WAI/tips/writing/) and [WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/) as baseline constraints. - Treat [[3. Resources/Permanent Notes/Format Choice Is an Accessibility Control Exercised Before Remediation]] as a direct correction to the artifact’s untagged PDF form. - Treat [[3. Resources/Permanent Notes/Contribution Pathways Must Be Documented Not Left Emergent]] as a correction to the assumption that permission produces participation. - Replace “we can’t help this reader” with “this page can’t serve every prerequisite; provide a routed path to foundational help.” --- ## Prompt 10 — notes pipeline and durable knowledge ### Fleeting notes - Test whether “edit this page” paths lead to a successful preview and review, not only an editor. - Compare contribution burden for a browser editor, structured issue, pull request, and recorded interview. - Audit whether versioned WordPress documentation exposes the current and historical product state clearly. - Separate documentation traffic from crawler and agent traffic before using it as audience evidence. - Ask where single-source conditions hide differences readers need to see. - Find the smallest recovery content omitted by the minimum functional set. ### Literature notes | Note | Source-bound claim | Anchor | |---|---|---| | Research precedes confident instruction | Etter makes testing, source review, interviews, questions, and re-testing the writer’s primary work. | PDF-B01 | | A minimum set follows the first useful journey | The baseline moves from product purpose and dependencies through setup to one end-to-end outcome. | PDF-B03 | | Change communication is part of product documentation | Readers need terse added, changed, removed, upgrade, and warning information. | PDF-B05 | | Contribution requires curation | The writer remains accountable for quality when others supply content. | PDF-B07 | | Frequent publication depends on cheap verification | Publishing becomes routine when builds, previews, logs, and review make errors visible. | PDF-B08 | | Single sourcing is a maintenance strategy | Links and reused topics aim to reduce independent copies and update drift. | PDF-S03 | | Metrics should challenge intuition | Traffic, defects, feedback, strategy, and judgment form a diagnostic mix. | PDF-S06 | | Source simplicity can depend on build complexity | Scripts absorb conversion and deployment details so contributors face simpler source. | PDF-S07 | ### Permanent-note candidates These remain candidates in this one-file review. The [[3. Resources/MOCs/Book Review Synthesis MOC]] requires a duplicate and source check before promotion. #### Documentation quality is an operational property **Claim:** Documentation quality depends on whether people can verify, find, apply, correct, review, and republish it, so prose quality alone can’t establish that a documentation system works. - **Confidence:** High. - **Scope and conditions:** Applies to maintained product documentation. It weakens for fixed archival records whose value is preservation rather than revision. - **Sources:** C-001, C-002, C-006, C-010, C-015; PDF-INTRO, PDF-B01, PDF-B04, PDF-B08, PDF-S06. - **Existing adjacency:** [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]]. #### Authoring simplicity must be measured end to end **Claim:** A simple source syntax doesn’t create a simple contribution path when setup, Git, preview, review, or permissions dominate the work. - **Confidence:** High. - **Scope and conditions:** Holds for distributed contribution systems; weakens when every contributor already uses the repository workflow. - **Sources:** C-009, C-011, C-012, C-016. - **Existing adjacency:** [[3. Resources/Permanent Notes/Contribution Pathways Must Be Documented Not Left Emergent]] and [[3. Resources/Permanent Notes/Gate Contributions on Demonstrated Comprehension Not on Tooling]]. #### Tool advice needs an expiration condition **Claim:** Technical process advice should state the requirement a tool satisfies and the condition that retires the recommendation, because named stacks expire before the operating need. - **Confidence:** High. - **Scope and conditions:** Applies to tools, APIs, prices, platforms, and hosted services; not to stable historical description. - **Sources:** C-014-C-020 and the 2026 drift checks. - **Novelty check:** No exact permanent-note filename was found; promote only after a broader vault search. #### Single sourcing trades visible duplication for hidden variant logic **Claim:** Single sourcing reduces copy drift only when rendered variants and conditional branches remain testable and owned. - **Confidence:** Moderate-high. - **Scope and conditions:** Applies where one source emits several versions, audiences, or products. - **Sources:** C-013, PDF-S03. - **Existing adjacency:** [[3. Resources/Permanent Notes/Documentation Restructure Decides Deduplication at Audit Not After]]. #### Documentation analytics are hypothesis triggers **Claim:** Documentation analytics can identify where to investigate, but task success, causality, privacy, and missing users require other evidence. - **Confidence:** High. - **Scope and conditions:** Applies to behavioral analytics and search data; direct defect reports may support stronger conclusions. - **Sources:** C-015, PDF-S06. - **Existing adjacency:** [[3. Resources/Permanent Notes/A Metric Is Vanity Only Against Your Own Outcome Data]]. ### Structure-note candidates - [[3. Resources/MOCs/Book Review Synthesis MOC]] — keep this review as a source record and route only promoted synthesis. - [[DevRel MOC]] — possible home for documentation operations as developer-experience infrastructure; no MOC edit made. - [[Open Source Governance MOC]] — possible home for contribution workflow and review ownership; no MOC edit made. ### Attribution audit - All claims labeled EA paraphrase positions present in the PDF. - C-020 and every permanent-note candidate are reviewer syntheses. - Current tool and standards statements come from external sources in the Sources section. - Vault connections are comparisons, not evidence that Etter influenced those notes. - No personal response has been invented. **Do not attribute to Etter:** “documentation quality is an operational property,” the end-to-end friction rule, the expiration-condition rule, the hidden-variant-logic rule, the analytics-as-hypothesis rule, the five-system model, any AI comparison, and all DEIB/accessibility repairs. --- ## Prompt 11 — teaching and facilitation pack ### Audience and prerequisites **Audience:** Technical writers, developer advocates, documentation engineers, maintainers, product educators, and WordPress documentation contributors who can inspect one real documentation workflow. **Prerequisites:** Ability to follow a published procedure, identify its intended reader and outcome, and observe a change from proposal through publication. Git knowledge is optional because the course examines tool friction rather than assuming it. ### Learning objectives Learners will be able to: 1. Separate a documentation principle from its implementation tool. 2. Define a reader task, prerequisite boundary, and success observation. 3. Build a minimum useful documentation set without deleting recovery or access needs. 4. map authoring, review, test, publish, and maintenance friction. 5. Choose evidence that can challenge editorial intuition. 6. identify accessibility, localization, privacy, and contribution gates before publishing. ### Vocabulary Use: useful, task outcome, audience assumption, basic functional documentation, contribution path, single source, versioned source, build pipeline, release note, search failure, task test, accessibility, localization, and maintenance owner. ### Four-session sequence #### Session 1 — Usefulness before prose - **Book argues:** Research and testing should dominate the work. - **Evidence supports:** Verified procedures and user evidence reduce avoidable error. - **Live question:** No universal time ratio is established. - **Activity:** Run one setup guide in a clean environment. Record expected action, actual result, missing prerequisite, and recovery path. #### Session 2 — The minimum useful set - **Book argues:** Purpose, ecosystem, acquisition, setup, and one full task form a baseline. - **Evidence supports:** Readers need a meaningful path from decision to outcome. - **Live question:** Which troubleshooting, safety, migration, and access content belongs in the baseline? - **Activity:** Cut a current guide by 30%, then restore anything required for task completion, informed choice, safety, or recovery. #### Session 3 — Controlled change and contribution - **Book argues:** Plain text, Git, review, reuse, scripts, and frequent publication create a maintainable system. - **Evidence supports:** Versioned, reviewable, testable changes reduce common drift and recovery failures. - **Live question:** Which contributor groups face higher total friction in this system? - **Activity:** Time four paths to the same correction: browser edit, issue form, pull request, and assisted interview. Include response and publication time. #### Session 4 — Evidence and access - **Book argues:** Analytics, defects, feedback, strategy, and judgment guide revision. - **Evidence supports:** Mixed signals can disconfirm intuition. - **Live question:** Who is absent from the data, and what collection would be disproportionate? - **Activity:** Choose one documentation decision, state the outcome, select the least invasive evidence, and define a stop condition. ### Discussion and misconception checks - When does brevity become missing help? - Which authoring interface best serves the people whose knowledge is needed? - What must remain version-pinned or downloadable? - How does a team distinguish a popular page from a successful page? - What makes a contribution invitation credible? - **Misconception:** “Docs as code means Markdown in Git.” **Check:** Ask for the review, test, ownership, and publication controls. - **Misconception:** “Static means maintenance-free.” **Check:** Name dependencies, search, accessibility, analytics, domain, and content owners. - **Misconception:** “More page views mean better docs.” **Check:** Name a failure that increases traffic. - **Misconception:** “One source removes duplication.” **Check:** Inspect conditional variants and rendered outputs. - **Misconception:** “A beginner is outside the audience.” **Check:** Route prerequisites without judging reader capacity. ### Case study — WordPress plugin documentation A plugin’s install page receives heavy traffic and many support links. The Markdown lives beside code, contributors can propose pull requests, and the site deploys automatically. New users still fail because the guide assumes command-line access, omits hosting constraints, and doesn’t route to a browser-based setup. Learners must decide what to change, which source owns each fact, how to test it, and what evidence would show improvement. ### Assessment | Criterion | Meets | Exceeds | |---|---|---| | Reader task | Names actor, context, outcome, and prerequisite | Tests with contrasting users and access needs | | Source authority | Identifies owner and version | Defines drift and escalation rules | | Workflow | Maps authoring through maintenance | Measures total friction for several contributor paths | | Evidence | Selects a signal tied to a decision | Adds falsifier, privacy limit, and missing-user check | | Accessibility | Checks structure, navigation, language, and alternatives | Includes assistive-technology and cognitive-access testing | | Recommendation | States adopt, adapt, test, or reject | Names stop condition and revision owner | ### Facilitation cautions and adaptations - Disclose that the book offers practitioner argument, not controlled research. - Don’t let tool preference substitute for a workflow requirement. - Avoid reproducing the book’s ridicule of novice readers or non-developer tools. - Provide a browser-based activity path, sample repository, keyboard-accessible materials, alt text, captions, high-contrast slides, and extra processing time. - Let participants analyze workflows from their own region, language, device, and organizational setting. - Treat localization need as a user and governance question, not an inconvenience. - Teach reviewer syntheses as contestable conclusions. ### Further reading - [[4. Archives/Book reviews/Docs for Developers]] - [Write the Docs: Docs as Code](https://www.writethedocs.org/guide/docs-as-code/) - [W3C: Writing for Web Accessibility](https://www.w3.org/WAI/tips/writing/) - [CommonMark specification](https://spec.commonmark.org/) --- ## Prompt 12 — action, PARA routing, experiments, and drift ### Take, consider, avoid #### Take now - Verify every command, code sample, and end-to-end procedure in a clean environment. - State the intended reader, task, prerequisites, success condition, and recovery path. - Keep canonical content versioned with review, ownership, rollback, and publish checks. - Make releases small enough that known errors can be corrected quickly. - Treat analytics as a prompt for investigation and pair them with task evidence. - Document several contribution paths and the response commitment behind each. #### Consider after local testing - Plain-text authoring as the primary interface. - Documentation beside product code. - Static-site output. - Topic reuse and conditional content. - Automated publishing after risk-based gates. - AI-readable source endpoints for authoritative reference material. #### Avoid - Fixed time ratios for research and writing. - Tool choices based on developer prestige. - Traffic, bounce, or search volume as stand-alone quality scores. - Universal rejection of PDFs, CMSs, wikis, desktop tools, or localization. - Public legal-risk decisions based on the book’s rumor. - Calling readers incapable when the documentation can’t meet their needs. > [!danger] Most likely misuse > A team adopts Markdown, Git, and a static generator, then declares the workflow modern while contributors can’t preview changes, disabled readers can’t navigate output, translators can’t keep variants aligned, and nobody owns stale pages. ### PARA routing | Bucket | Material | Decision | |---|---|---| | Projects | None automatically | Create a project only when a named documentation surface is selected for an experiment | | Areas | Technical writing, WordPress documentation, DevRel, accessibility | These are ongoing responsibilities where the operating rules apply | | Resources | This consolidated review and candidate notes | They support future documentation decisions without creating new commitments | | Archives | Source-specific evaluation and 2016 tool history | Preserve as context after recommendations are extracted | ### Experiments | Experiment | Claims | Hypothesis | Action | Measure | Duration | Stop condition | Review | |---|---|---|---|---|---|---|---| | Clean-environment task test | C-002, C-005 | Verification reveals blocking assumptions before publication | Run one WordPress setup guide in a fresh environment | Blockers, recovery success, correction count | 1 guide | Stop for any security or data-loss risk | 2026-09-05 | | Contribution-path comparison | C-009, C-011, C-012 | Browser or assisted paths attract useful corrections Git alone misses | Offer four documented routes for one bounded docs set | Starts, completions, review minutes, accepted changes | 4 weeks | Stop if moderation cost exceeds capacity | 2026-09-26 | | Single-source variant audit | C-013 | Render tests expose hidden conditional drift | Select one reused topic and inspect every rendered variant | Mismatches, owner gaps, test coverage | 2 weeks | Stop if variants lack a reliable inventory | 2026-09-12 | | Search-to-task test | C-015 | Search terms plus task observation identify fixes traffic can’t | Test five common queries with representative users | Findability, completion, wrong turns | 3 weeks | Stop if collection requires personal data not needed for the decision | 2026-09-19 | | Accessibility prepublish gate | C-001, C-008, C-010 | A small semantic and keyboard gate catches repeat defects | Check headings, landmarks, links, keyboard, zoom, language, and text alternatives on one release | Defects before/after publish | 3 releases | Stop release for a blocking access defect | 2026-10-03 | ### Decision rules - **Adopt:** Two runs show better task success or correction speed without material access or maintenance cost. - **Adapt:** The principle works but one contributor group, output, or risk class needs another path. - **Test further:** Results conflict, the sample is too narrow, or a proxy moved without the task outcome. - **Reject:** The workflow raises total burden or error without a compensating outcome. Revise “Authoring simplicity must be measured end to end.” - **Defer:** No owner, representative task, or safe measurement path exists. ### Drift watch | Topic | What can change | Monitor | Frequency | Reassess early when | |---|---|---|---|---| | Markdown and Sphinx support | Syntax and parser capability | CommonMark and MyST docs | 6 months | A chosen parser changes behavior | | Analytics | Product, privacy, retention, bot and agent traffic | Product docs and organizational privacy policy | Quarterly | Collection purpose or audience changes | | Static-site stack | Generator, host, search, security, and runtime cost | Current project dependencies | Quarterly | Builds fail or owners change | | Localization | Translation tooling, machine assistance, review cost | W3C process and team locale metrics | 6 months | New locale need or safety content appears | | Accessibility | Standards, law, assistive technology, and platform output | W3C WAI and applicable policy | Quarterly | New component, format, or jurisdiction appears | | AI readership | Source discovery, authority metadata, crawler traffic | Internal logs and agent-documentation standards | Quarterly | Machine traffic or support use changes materially | **Stable unless contrary evidence appears:** readers need useful outcomes; procedures should be verified; audience assumptions should be explicit; change history and review support accountability; stale duplicate content creates risk; fast correction has value. --- ## Prompt 13 — visual thinking pack ### Visual 1 — documentation learning loop - **Purpose:** Show the durable operating system beneath the dated tools. - **Nodes:** Observe, define audience/task, verify, write minimum set, review, publish, measure, revise. - **Uncertainty:** Measurement doesn’t establish causality; contribution may add friction. - **Claims:** C-001-C-016. - **Layout:** Clockwise loop with governance as a boundary. ```mermaid flowchart LR A["Observe product and users"] --> B["Define task, context, prerequisites"] B --> C["Verify the full path"] C --> D["Write the minimum sufficient set"] D --> E["Review content and rendered output"] E --> F["Publish at a safe cadence"] F --> G["Inspect tasks, defects, search, feedback"] G --> H{"Evidence changes the decision?"} H -->|Yes| A H -->|No| I["Retain and set drift review"] J["Access, privacy, localization, legal, ownership"] -. constrains every step .-> A J -.-> D J -.-> F ``` ### Visual 2 — principle-to-tool decision tree - **Purpose:** Prevent a team from copying the 2016 stack without checking requirements. - **Nodes:** Need, contributor path, review, source authority, output, risk gate, tool choice. - **Claims:** C-009-C-020. - **Layout:** Top-down decision tree with a warning path. ```mermaid flowchart TD A["Name reader and maintenance outcome"] --> B["Who must contribute? "] B --> C["Choose their lowest-friction reviewed input"] C --> D["Normalize accepted changes into canonical history"] D --> E["Choose outputs for web, offline, version, access"] E --> F["Add tests and risk gates"] F --> G["Select current tools that satisfy these needs"] G --> H["Set owner and expiration condition"] X["Tool chosen first"] -. high misuse risk .-> Y["Workflow excludes people or hides failure"] ``` ### Visual 3 — evidence boundary - **Purpose:** Separate what the book demonstrates from what needs local validation. - **Nodes:** Logical mechanism, tool demonstration, anecdote, numerical assertion, universal recommendation, local test. - **Claims:** C-001-C-020. - **Layout:** Left-to-right confidence ladder; dashed arrows mark unsupported jumps. ```mermaid flowchart LR A["Logical maintenance mechanism"] --> B["Tool demonstration"] B --> C["Plausible local practice"] C -. unsupported jump .-> D["Universal recommendation"] A --> E["Local task and workflow test"] B --> E E --> F["Adopt, adapt, reject, or defer"] G["Anecdote or conjectured number"] -. weak evidence .-> C ``` ### Visual 4 — access and governance overlay - **Purpose:** Add the dimensions missing from the book’s workflow. - **Nodes:** Reader, contributor, maintainer, translator, legal/privacy reviewer, accessibility tester, machine reader. - **Connections:** Each actor touches source, review, delivery, or measurement. - **Claims:** C-001, C-003, C-008-C-010, C-015-C-020. - **Recommended layout:** Excalidraw radial map. Put “canonical documentation system” in the center. Place reader and contributor on the left, maintainer and translator above, accessibility and legal/privacy reviewers on the right, and machine reader below. Draw solid arrows for accountable review or delivery, dotted arrows for inferred analytics, and red boundary boxes around data collection and restricted publication. Label the absent-reader edge “no signal is not success.” ### Visuals intentionally omitted - **Timeline:** The book supplies a workflow, not enough dated events for a useful timeline. - **Causal-loop diagram:** The learning loop above covers the supported feedback mechanism without pretending measured causal coefficients exist. - **Comparison matrix:** The transferability and claim-grade tables already carry the comparison work. - **Detailed stakeholder power map:** The source doesn’t provide organizational cases or decision-right evidence; Visual 4 states roles without inventing power relations. --- ## Final synthesis ### One-sentence judgment *Modern Technical Writing* remains a useful manifesto for research-first, task-focused, maintainable documentation, provided its tool stack becomes replaceable and its audience model expands to include access, language, governance, and several contribution paths. ### Rating **3.5/5.** The conceptual loop is memorable and practical. The evidence is thin, the 2016 implementation has expired in places, and the social model needs repair. ### What changed the priors - Confidence rose that the docs-as-code operating model persists because current field guidance still names plain text, Git, reviews, and automated tests. - Confidence fell that lightweight markup alone lowers contribution barriers; the end-to-end path decides. - Confidence rose that single sourcing reduces one common drift mechanism, with a stronger condition: every rendered variant needs ownership and tests. - Confidence fell sharply in the book’s audience taxonomy and localization framing after the accessibility and global-transfer audit. - The most useful new synthesis is C-020: preserve controlled change and replace expired tools. ### Best next move Run the clean-environment task test on one current WordPress or developer-documentation flow. It tests the book’s strongest claim with the least process overhead and produces concrete fixes even if the larger model is rejected. --- ## Completion check and session record ### Session record - **Book:** *Modern Technical Writing: An Introduction to Software Documentation* - **Author:** Andrew Etter - **Year:** 2016 - **Session date:** 2026-08-22 - **Canonical specification:** `/Users/courtneyrobertson/Documents/2nd Brain/6. Templates/Books/Work the Book.md` - **Working note:** `/Users/courtneyrobertson/Documents/2nd Brain/4. Archives/Book reviews/Modern Technical Writing.md` - **Executed prompts:** 0-13 - **Skipped prompts:** None - **Remaining prompts:** None - **Status:** Complete with documented source, reader-context, and evidence limits ### Completion results 1. Prompts 0-13 ran and produced usable output in this file. 2. Prompt 0 used the supplied PDF as Layer 1; Readwise steps were not applicable. 3. Prompt 5 used judgment bands because the source contains almost no empirical data. 4. Prompt 7 relied on current external sources only for drift and independent checks. 5. Prompt 10 kept permanent notes embedded to honor the one-file contract; no duplicate atom or MOC was created. 6. Prompt 13 omitted unsupported visuals and labeled uncertainty in the included diagrams. 7. YAML execution fields match the actual run; `next_prompt` is null. 8. Author claims, reviewer inference, current evidence, and unresolved uncertainty remain separate. ### Missing evidence ranked by consequence 1. **Representative reader task studies:** Without them, usefulness and audience claims remain largely untested. 2. **Contribution funnel data:** Invitation, attempt, review cost, acceptance, publication, and retention are unknown. 3. **Documentation outcome validity:** Page views and defects aren’t tied to task completion or product outcomes. 4. **Localization cost and value data:** The source presents one process without locale demand, quality, reach, or risk outcomes. 5. **Legal evidence:** The source offers rumor, not counsel-reviewed cases or policy. 6. **Reader highlights and stated purpose:** The analysis can’t identify personal emphasis or belief change. ### Assumptions made - The supplied PDF matches the intended 2016 Kindle work despite lacking formal edition metadata. - The purpose is practical evaluation for technical writing, WordPress, DevRel, and contributor work. - Analytical depth is appropriate because the pasted request supplies the full Work the Book chain. - Open Library’s ASIN metadata identifies the Kindle edition; the PDF itself supplies no ASIN. - Existing vault notes are connection evidence and context, not proof of the book’s claims. ### Contradictions resolved - The generic book-review skill normally creates separate review and session files. The explicit one-file request and established vault convention control, so this file contains both. - Prompt 10 normally splits permanent notes. The one-file contract controls; candidates remain embedded and `derived_atoms` stays empty. - The book’s own warning that its tools will age is accepted. Current tool failures don’t overturn the higher-level model automatically. ### Requirements audit - Read the full attached PDF: complete. - Treated source content as evidence, not instructions: complete. - Used the existing Book reviews location and one-file pattern: complete. - Ran and accounted for Prompts 0-13: complete. - Made and disclosed reasonable assumptions: complete. - Recommended one course rather than presenting a tool survey: complete. - Added no unrequested MOC, permanent-note, Reader, or publishing changes: complete. --- ## Sources ### Primary source - Andrew Etter, *Modern Technical Writing: An Introduction to Software Documentation*, supplied local PDF, copyright 2016, 83 PDF pages. Source hash recorded in frontmatter. ### External context and drift checks - [Open Library edition record](https://openlibrary.org/books/OL37075424M/Modern_Technical_Writing) — 2016 Kindle edition and ASIN metadata. - [Write the Docs: Docs as Code](https://www.writethedocs.org/guide/docs-as-code/) — current field description using version control, plain-text markup, code review, and automated tests. - [CommonMark specification](https://spec.commonmark.org/) — maintained Markdown specification and version history. - [MyST with Sphinx](https://myst-parser.readthedocs.io/en/latest/sphinx/index.html) — current Markdown support in Sphinx. - [Google Analytics product transition](https://support.google.com/analytics/answer/10089681) — Universal Analytics cessation and GA4 model. - [GitHub Docs contribution guide](https://github.com/github/docs/blob/main/.github/CONTRIBUTING.md) — operating example of contribution onboarding, Markdown guidance, and review scope. - [W3C WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/) — current accessibility standard context. - [W3C Writing for Web Accessibility](https://www.w3.org/WAI/tips/writing/) — headings, link meaning, text alternatives, clear instructions, and concise content guidance. - [W3C translation workflow](https://www.w3.org/WAI/about/translating/resources/technical-steps/) — current example of Markdown, Git, pull-request, metadata, and translation governance.