# The Product is Docs > [!summary] Recommendation > Use this as an operating handbook and discussion starter, especially for integrating writers into product work, defining audiences, testing procedures, closing feedback loops, and maintaining existing content. Do not adopt its Splunk-specific ratios, office-centered remote-work advice, measurement examples, or coercive review tactics without local testing. The authors openly describe the book as experience-based guidance rather than scholarship, which makes its limits easier to manage. **Rating: 3.5/5.** ## Why this book belongs in this vault The book connects technical writing to product management, developer experience, support, UX, QA, and community work. It belongs beside [[3. Resources/Readwise/Articles/Documentation Done Right A Developer’s Guide]], [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]], [[3. Resources/Permanent Notes/A Metric Is Vanity Only Against Your Own Outcome Data]], [[3. Resources/Permanent Notes/A Feedback Signal Not More Automation Is What Makes a System Self-Improving]], and [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review]]. Its strongest contribution is organizational. Good documentation is not downstream prose attached to a finished product. It is product work that discovers requirements, tests workflows, exposes poor design, records operating knowledge, and carries customer evidence across team boundaries. Its largest limitation follows from the same source: this is one enterprise documentation team’s operating experience, not a comparative study of documentation organizations. --- ## Prompt 0 — retrieval, provenance, and source map ### Source record | Field | Result | |---|---| | Supplied artifact | Local EPUB | | Integrity | Every archived file passed ZIP/EPUB integrity testing | | SHA-256 | `803fa126522462048ffcca6b31a4fd895618524779c351cdac2a96fe0dffae0a` | | Metadata | *The Product is Docs*, Christopher Gales and the Splunk Documentation Team, 2020 | | Edition | Second edition; the preface names four new chapters and four substantially revised chapters | | Extracted size | 71,268 plain-text words; 76,588 structure-preserving Markdown words | | Coverage | Preface, introduction, all 26 chapters, notes, and four figures | | Reader layer | No supplied highlights, notes, color data, timestamps, or Readwise record | | Primary anchor system | EPUB chapter anchors listed below | | External layer | Bibliographic check, publication history, later Splunk practice, and current accessibility standard | ### Layer 1 substitution The complete EPUB replaces Readwise as Layer 1. That substitution preserves the book text, chapter order, footnotes, and figures. It does not preserve reader emphasis. Every quoted or paraphrased hotspot in this note is selected by the analysis system, not by Courtney. No selection below should be interpreted as agreement, interest, or prior belief. ### Stable anchor scheme - `EPUB-PREF` — Preface to the Second Edition - `EPUB-C01` — Introduction - `EPUB-C02` — Agile - `EPUB-C03` — Audience - `EPUB-C04` — Collaborative Authoring - `EPUB-C05` — Customer Feedback and Community - `EPUB-C06` — Documentation Decisions - `EPUB-C07` — Documenting Third-party Products - `EPUB-C08` — Hiring, Training, and Managing Documentation Teams - `EPUB-C09` — Learning Objectives - `EPUB-C10` — Maintaining Existing Content - `EPUB-C11` — Measuring Success - `EPUB-C12` — Organizing Documentation Tiger Teams - `EPUB-C13` — Research for Technical Writers - `EPUB-C14` — Scenario-driven Information Development - `EPUB-C15` — Technical Editing - `EPUB-C16` — Technical Verification - `EPUB-C17` — Tools and Content Delivery - `EPUB-C18` through `EPUB-C24` — Cross-functional work with support, engineering, the field, marketing, product management, remote teams, and UX - `EPUB-C25` — Writing SaaS Documentation - `EPUB-C26` — Afterword and Acknowledgments - `EPUB-NOTES` — Twelve endnotes and cited works ### Ingestion summary - Twenty-six numbered chapters were found in EPUB spine order. The real chapter structure replaces inferred clusters. - The authors intentionally organize the essays alphabetically and state that no reading sequence is required (`EPUB-C01`). - The second edition adds chapters on documentation decisions, tiger teams, the field, and SaaS documentation (`EPUB-PREF`). - The main repeated topics are audience, customer outcomes, early cross-functional participation, feedback, verification, maintenance, and sustainable delivery. - The EPUB contains four informative figures: an investigation-heavy writing loop, a third-party documentation decision tree, a learning-objective matrix, and a page-view/negative-vote report. ### Artifact defects and limits 1. All four informative images lack `alt` attributes in the EPUB source. The images carry information that is not fully available to a screen-reader user. 2. The EPUB 2 package provides no modern accessibility metadata or conformance statement. 3. The navigation file points many chapter entries to the wrong split file and depends on position fragments from the source conversion. Reading order still works through the package spine. 4. The book cites twelve sources, but most operational recommendations remain uncited practitioner guidance. 5. Several numerical statements lack a method in the text, including the claim that feedback unanswered within 72 hours is unlikely ever to receive a response and the claim that Splunk conducted more than 80 customer conversations per week. --- ## Prompt 1 — reading contract, priors, and open questions > [!note] Inferred inputs > No explicit purpose, prior-belief inventory, constraints, or DEIB goal accompanied the EPUB. I set the purpose to evaluating the book as a practical operating guide for technical documentation in product, WordPress, and DevRel work; selected analytical depth; treated the one-file requirement as the main constraint; and used access, labor, and transferability as the inclusion lens. These are system assumptions, not reader beliefs. Replacing them would change the relevance and confidence judgments below. ### Reading contract - **Why read:** Test whether the book supplies practices worth carrying into current product-documentation work. - **What to understand:** Which practices create reliable, usable docs; who must own them; what evidence supports the advice; and what changed after 2020. - **Intended use:** A durable vault reference, a source of small operating experiments, and a teaching aid. - **Success criteria:** Recover the book’s operating model; separate tested practice from anecdote; identify transfer limits; produce actions that can be reversed if they fail. - **Evidence that would change the conclusion:** Comparative team studies, direct task-test results, replicated measurement methods, or evidence that a recommended practice causes more delay or exclusion than value. - **What the book cannot establish:** Universal staffing ratios, causal business effects of documentation, the best toolchain, or the effectiveness of Splunk practices in other organizations. - **Constraints:** One consolidated note; no reader highlights; no access to Splunk’s raw analytics, staff interviews, or internal process artifacts. ### Prior-belief and incentive guardrails Reader-supplied prior beliefs were unavailable. The analysis begins with system-selected priors: - Documentation works best when writers participate before implementation is complete. - Clear audience and task definitions improve documentation decisions. - Technical accuracy and editorial quality require different review passes. - Page views and support-case counts are weak proxies unless tied to a decision and outcome. - Tool changes rarely repair an undefined process. - Maintenance is product work, not leftover capacity. The inferred professional context could bias this analysis toward the book because its cross-functional model validates technical communication as product work. Prompt 7 therefore gives extra attention to unsupported status claims, hidden labor, and recommendations that expand the writer’s role without expanding authority or capacity. ### Open questions #### Definitions and mechanisms 1. What observable behavior makes documentation “part of the product” rather than adjacent content? 2. When does an audience definition improve decisions, and when does it harden stereotypes? 3. Does one learning objective per topic improve task success or only simplify authoring? 4. Which review stage catches which class of error? 5. When does open contribution improve freshness, and when does it diffuse ownership? #### Evidence and credibility 6. Which recommendations are based on repeated observation, and which are team preferences? 7. What evidence supports the 72-hour feedback claim? 8. How were Splunk’s customer conversations counted and evaluated? 9. Does the Rule of Five answer the business question posed, or only bound a median? 10. Which claims have independent support inside the book? #### Application and failure modes 11. How can a small or volunteer team apply the model without reproducing a large enterprise process? 12. How should writers refuse new cross-functional duties when staffing does not change? 13. What is the minimum viable technical-verification process for a rapid release? 14. How should teams prioritize maintenance against new feature work? 15. When does a tiger team repair a surprise, and when does it normalize planning failure? 16. Which documentation decisions need an explicit owner, expiry date, and reversal trigger? #### Access, power, and context 17. Who is excluded by office-centered collaboration assumptions? 18. How should disability access shape audience definitions, authoring tools, and task tests? 19. Does “diversity of thought” dilute attention to structural exclusion? 20. How does the model change for open source, public-sector, multilingual, low-bandwidth, or volunteer documentation? 21. Who has authority when a writer identifies a product defect but the release owner declines the fix? #### Current relevance 22. How do AI answer systems and machine readers change the audience for reference documentation? 23. Which 2020 tool recommendations remain useful as requirements rather than vendor choices? 24. How should analytics change when privacy controls, bots, and AI crawlers distort page-level traffic? ### Priors seed | Claim placeholder | Initial belief | Prior confidence | Reason | Evidence needed | |---|---|---:|---|---| | P-01 Early writer participation improves docs | 78% | High | Fits product-discovery and release experience | Before/after rework and task-error data | | P-02 Audience definitions improve content choices | 72% | Moderate | Plausible planning aid | Task success by defined audience segment | | P-03 Learning objectives improve each topic | 60% | Uncertain | Useful in instruction; transfer to every reference topic is unclear | Comparative topic tests | | P-04 Closed feedback loops improve docs | 82% | High | Error reports become changes only when owned | Resolution time and recurrence data | | P-05 Independent technical review is necessary | 85% | High | Author and source blind spots are predictable | Defect escape rates by review method | | P-06 QA should test high-risk procedures | 90% | High | Failed procedures can damage user systems | Procedure-test defect findings | | P-07 Maintenance should be continuous | 88% | High | Product and dependency drift are unavoidable | Staleness and support-cost trends | | P-08 Measurement must support decisions | 90% | High | Counting without a decision has no steering value | Documented decisions and changed actions | | P-09 Tool choice should follow requirements | 86% | High | Tool-first selection invites lock-in and process mismatch | Migration, upkeep, and user-outcome evidence | | P-10 Direct contact improves audience knowledge | 75% | Moderate | Removes internal filtering but can over-weight vocal users | Representative research and triangulation | ### Drift assumptions The author’s claims are fixed. The context used to evaluate them is not. Tool markets, AI-assisted authoring, search and answer interfaces, accessibility standards, analytics privacy, remote-work norms, and Splunk’s own publishing system can change within a year. Audience research, verification, maintenance, and decision-linked measurement are less time-sensitive. --- ## Prompt 2 — inspectional reading ### Central project - **Problem:** Technical-writing literature often treats content design or management separately and leaves gaps around daily work inside a fast product-development organization. - **Proposed answer:** Treat documentation as a cross-functional product capability guided by audience, customer outcomes, feedback, verification, maintenance, and flexible process. - **Method:** Twenty-six short essays based mainly on the Splunk Documentation Team’s experience, with selected references and internal examples. - **Audience:** Technical writers, documentation managers, and product colleagues who work with documentation teams. - **Assumptions:** Commercial software, a formal product organization, access to engineering and customer-facing teams, a dedicated documentation function, and enough authority to influence process. - **Rhetorical modes:** Teach, explain, advocate, document, and provoke discussion. The book explicitly disclaims scholarship and a complete prescription (`EPUB-C01`). ### Book map and coverage | Chapter | Apparent purpose | Main relationship to the project | Evidence | Coverage | |---|---|---|---|---| | Preface | Explain the second edition | Shows revision from community and team experience | Author report | Read | | 1. Introduction | Define scope and limits | Establishes experience-based operating guide | Author account | Read | | 2. Agile | Place docs in iterative product work | Makes early participation and realistic capacity foundational | Experience and Agile interpretation | Read | | 3. Audience | Turn intuition into explicit audience definitions | Grounds content, staffing, architecture, and style decisions | Splunk case study | Read | | 4. Collaborative Authoring | Define shared writing and ownership | Replaces single-author control with governed collaboration | Team examples | Read | | 5. Customer Feedback and Community | Build direct, responsive feedback | Supplies the learning signal for improvement | Splunk practice and unsupported counts | Read | | 6. Documentation Decisions | Make explicit, revisable choices | Joins goals, data, constraints, expertise, and feedback | Practical framework | Read | | 7. Third-party Products | Bound documentation responsibility | Uses a seven-option decision tree to limit maintenance risk | Decision logic | Read | | 8. Teams | Hire, train, manage, grow, and shrink | Connects staffing, diversity, collective intelligence, and capacity | Experience plus cited diversity research | Read | | 9. Learning Objectives | Plan around observable reader outcomes | Joins audience, scope, structure, and evaluation | Instructional-design adaptation | Read | | 10. Maintenance | Treat existing content as a live system | Extends product change into dependency-aware content work | Detailed practice | Read | | 11. Measuring Success | Link measures to decisions | Rejects counting as measurement without action | Hubbard, support-deflection examples, Splunk report | Read | | 12. Tiger Teams | Recover from an unplanned deadline | Offers a temporary parallel-work structure | Experience and hypotheticals | Read | | 13. Research | Find fact and meaning | Frames writers as investigators who test primary sources | Worked examples | Read | | 14. Scenarios | Connect features to real goals | Builds end-to-end problem-solving content | Method and examples | Read | | 15. Technical Editing | Test clarity, cohesion, and access | Defines editorial review as collaboration | Detailed practices and checklist | Read | | 16. Technical Verification | Test accuracy and procedures | Separates source review from executable truth | Detailed review process | Read | | 17. Tools and Delivery | Select for reader and author needs | Treats tools as requirements decisions, not identities | Decision questions and Splunk wiki case | Read | | 18–24. Cross-functional work | Define interfaces with support, engineering, field, marketing, PM, remote teams, and UX | Makes writers cross-team context carriers and user advocates | Team practices and anecdotes | Read | | 25. SaaS | Adapt the model to continuous service | Adds shared-responsibility docs, runbooks, and fleet risk | Splunk Cloud practice | Read | | 26. Afterword | Restate cross-functional purpose | Confirms selective-use design and invites feedback | Author statement | Read | ### Provisional 150-word summary *Provisional after inspection, confirmed by analytical reading:* Christopher Gales and the Splunk Documentation Team argue that technical documentation succeeds when writers operate as full product-team members. Writers define audiences, turn user goals into learning objectives, investigate the product firsthand, challenge poor UX, coordinate with every customer-facing group, and treat review, testing, feedback, and maintenance as continuous work. The book offers a broad catalog rather than a sequence or universal method. Its most useful sections turn tacit practice into decisions: how to scope third-party coverage, evaluate tools, plan maintenance, structure reviews, test procedures, and choose measures that reduce uncertainty about a real decision. Its evidence is strongest as transparent practitioner testimony and weakest where a Splunk observation becomes a general rule. The 2020 edition also carries office-centered assumptions, limited disability analysis, and pre-generative-AI concepts of readership. Read it as a set of hypotheses and operating checks, then test them in the local organization. ### Reading hotspots | Hotspot | Why it deserves attention | |---|---| | Introduction (`EPUB-C01`) | Defines the experience-based evidence boundary | | Agile (`EPUB-C02`) | Makes documentation part of product flow but also reveals capacity and office assumptions | | Audience (`EPUB-C03`) | Gives the book’s main reader-modeling method | | Documentation Decisions (`EPUB-C06`) | Provides the broadest reusable decision process | | Learning Objectives (`EPUB-C09`) | Supplies a testable alternative to feature-centered scope | | Maintenance (`EPUB-C10`) | Treats changes as a dependency graph, not isolated page edits | | Measuring Success (`EPUB-C11`) | Separates counting, inference, and decision support | | Research (`EPUB-C13`) | States the primary-source and hands-on verification ethic | | Technical Editing and Verification (`EPUB-C15`, `EPUB-C16`) | Splits clarity review from technical truth testing | | Tools and Delivery (`EPUB-C17`) | Preserves useful criteria even as named tools age | | UX and SaaS (`EPUB-C24`, `EPUB-C25`) | Extends documentation into design and service operations | ### Reading strategy **Recommendation: selective deep read after one inspectional pass.** Read chapters 1, 3, 6, 9–11, 13, 15–17, 24, and 25 closely; use the remaining essays as situation-specific references. Switch to a full comparative read only when designing a documentation organization or teaching a complete course. Stop treating a chapter as prescriptive when its recommendation depends on Splunk’s scale, hierarchy, customer access, or toolchain. --- ## Prompt 3 — classification and terminology ### Classification - **Domain:** Technical communication and software product development - **Subdomains:** Documentation operations, content design, developer experience, product management, SaaS operations - **Genre:** Multi-author practitioner handbook and essay collection - **Argument type:** Mainly practical and prescriptive, supported by descriptive company cases - **Primary method:** Experience report, decision heuristic, checklist, and worked example - **Intended use:** Selective reference, team discussion, process design, and professional training - **Comparison traditions:** Information development, user-centered design, instructional design, Agile, docs as code, knowledge management, and customer-support operations ### Controlled vocabulary Definitions below are paraphrases unless quotation marks appear. | Term | Author’s use | Competing meaning | Operational definition for this note | Equivocation risk | Example / counterexample | Evidence | |---|---|---|---|---|---|---| | Audience definition | Shared description of user type, capability, role, and goal | Persona with a name and narrative context | Evidence-backed segment used to change a content decision | Can become a stereotype without validation | Admin capability tier / invented “average user” | `EPUB-C03` | | Persona | Concrete individual instance of an audience type | Any user segment | Research-based scenario character | Often used as a synonym for audience | Named admin in context / capability table | `EPUB-C03` | | Learning objective | Observable intellectual outcome supporting a user goal | Course objective or topic purpose | What a reader can identify, decide, or do after the content | “Understand” hides an untestable result | Configure an alert / know alerts | `EPUB-C09` | | User goal | Real-world problem, decision, or completed task | Feature adoption target | Outcome outside the document that motivates reading | Product goals can be mislabeled as user goals | Monitor login failures / learn feature X | `EPUB-C09` | | Scenario | End-to-end real problem solved with the product | Tutorial, use case, or marketing case | Validated workflow for a named audience and goal | Can become a polished but invented success story | Diagnose failed logins / feature tour | `EPUB-C14` | | Customer feedback | Direct response from a product or documentation user | Survey score or support ticket count | Traceable input with an owner, response, and disposition | Vocal users can be mistaken for all users | Page feedback resolved and retested / unowned comment box | `EPUB-C05` | | Community | People, connections, and content around product use | Marketing audience or forum membership | Users and contributors who exchange product knowledge | Commercial customer language narrows non-customer communities | Active Q&A participants / email list size | `EPUB-C05` | | Documentation decision | Choice about scope, sequence, medium, or investment | Any writer preference | Recorded option chosen from audience, outcome, constraints, data, and expertise | “Data-driven” can hide judgment | Defer low-value page with rationale / copy existing structure by habit | `EPUB-C06` | | Collective intelligence | Writers sharing product context across assignments | Group consensus | Deliberate cross-team process that routes consequential knowledge | Can become invisible coordination labor | Dependency alert to another writer / everyone watches everything | `EPUB-C08` | | Technical editing | Feedback on clarity, usability, relevance, style, and information design | Copyediting | Review of whether intended readers can parse and navigate the content | Can be confused with factual verification | Audience and structure review / spellcheck only | `EPUB-C15` | | Technical verification | Independent review or execution for accuracy and completeness | Editorial review | Named reviewer checks claims; QA executes risky procedures | Approval can be mistaken for testing | Fresh-environment task run / “looks good” comment | `EPUB-C16` | | Measurement | Reduction of decision-relevant uncertainty | Counting available activity | Evidence collected to choose or revise an action | Precision can disguise proxy weakness | Compare task success before a rewrite / report page views alone | `EPUB-C11` | | Support deflection | Avoided support demand because self-service worked | Any fall in case volume | Estimated causal change with stated counterfactual and uncertainty | Measures an absence and invites attribution error | Controlled survey plus trend bounds / page view followed by no case | `EPUB-C11` | | Tiger team | Temporary specialists solving a bounded urgent problem | Standing surge capacity | Time-boxed recovery team with owner, scope, exit, and retrospective | Can normalize chronic understaffing | One release recovery / permanent crisis mode | `EPUB-C12` | | Documentation platform | Combined authoring, management, and delivery capabilities | A vendor product | Toolchain selected from reader, author, governance, migration, and upkeep requirements | Feature lists can replace needs analysis | Portable source with maintained build / proprietary lock-in without exit plan | `EPUB-C17` | | Runbook | Tested internal procedure for a repeatable service operation | Any internal note | Versioned, reviewed, executable operational task with prerequisites and failure guidance | A stale checklist can look authoritative | Incident recovery procedure / meeting notes | `EPUB-C25` | ### Contested language - **Agile:** The book alternates among manifesto values, scrum ceremonies, and general adaptability. Those are related but not interchangeable. - **Accessible:** Sometimes means easy to understand, sometimes available in a format, and sometimes disability access. Each use needs a named criterion. - **Customer success:** Can mean task completion, satisfaction, adoption, renewal, or company revenue. - **Quality:** Covers accuracy, completeness, consistency, style, usability, and delivery timing. A quality gate must name which dimension it checks. - **Community:** The commercial product framing does not fully cover volunteer governance, contributor rights, or public-interest users. - **Done:** Can mean code complete, release complete, documented, tested, or usable by the audience. - **Good enough:** Reasonable for reversible, low-risk content; dangerous for security, destructive operations, or high-scale SaaS changes. ### Category-error watch | Risk | Status | Assessment | |---|---|---| | Correlation versus causation | Present | Positive feedback, adoption, brand, and support outcomes are sometimes linked without isolation of other causes | | Individual versus institutional behavior | Present | Writers are asked to compensate for missing product processes, authority, or staffing | | Description versus prescription | Present | Splunk practices sometimes shift into general instructions | | Identity versus behavior | Present | Audience labels can imply stable identities when task context may explain behavior better | | Intention versus effect | Present | Inclusive intent is discussed without outcome measures or procedural safeguards | | Anecdote versus population evidence | Present | Most chapters use team stories and hypothetical cases | | Legal versus moral claims | Not materially applicable | The book does not build a legal argument | | Technical capability versus practical outcome | Present | A tool feature or feedback channel does not guarantee use, upkeep, or reader success | | Absence of evidence versus evidence of absence | Present | Early literature searches are used to describe topic gaps but cannot establish that no relevant model existed | | Theological versus historical claims | Not applicable | Outside the book’s domain | --- ## Prompt 4 — claims, dependencies, and falsifiers ### Source labels - **EA:** Explicit author claim - **IA:** Implied author claim - **Q3P:** Quoted or cited third-party claim - **RI:** Reader/system inference; not the author’s sentence - **UI:** Unresolved interpretation ### Claims inventory | ID | Source | Claim | Type and scope | Testability and expected evidence | Serious falsifier | Main terms | Source | |---|---|---|---|---|---|---|---| | C-001 | EA | Documentation belongs inside product development rather than after it | Prescriptive; software teams | Compare late rework, coverage, and task defects by participation timing | Early participation adds cost without reducing defects or rework | Agile, done | `EPUB-C02` | | C-002 | EA | Writers can improve product UX by identifying explanation-heavy design | Practical; feature work | Track writer-raised design changes and task outcomes | Writer involvement adds conflict but no detectable usability gain | user advocate, UX | `EPUB-C24` | | C-003 | EA | Explicit audience definitions improve content and team decisions | Methodological; doc sets | Audience validity plus task and findability tests | Decisions based on definitions perform no better or increase exclusion | audience definition | `EPUB-C03` | | C-004 | EA | A topic usually benefits from one observable learning objective | Prescriptive; topic-level content | A/B task tests and maintenance comparison | Multi-objective topics outperform without added confusion or upkeep | learning objective | `EPUB-C09` | | C-005 | EA | Feedback mechanisms must lead to acknowledgment and action | Moral and practical; feedback systems | Resolution, recurrence, and user follow-up data | Unanswered feedback performs equally well for trust and correction | feedback loop | `EPUB-C05` | | C-006 | IA | Direct customer contact improves a writer’s audience model | Causal; documentation research | Compare hypotheses before and after representative interviews | Direct contact systematically overweights vocal users and worsens choices | customer contact | `EPUB-C05` | | C-007 | EA | Documentation choices improve when tied to audience, outcomes, constraints, data, and expertise | Methodological; planning | Decision records and later outcome review | Lightweight intuition produces equal or better results at lower cost | documentation decision | `EPUB-C06` | | C-008 | EA | Third-party coverage should be the minimum needed for customer success | Prescriptive; integrations | Maintenance cost, task success, and support data by coverage level | Limited coverage causes repeat failure that fuller maintained guidance prevents | third-party docs | `EPUB-C07` | | C-009 | EA | Diverse teams improve innovation, collaboration, and business outcomes | Causal; teams | Independent organizational studies with defined diversity and controls | Controlled evidence shows no benefit or harm under stated conditions | diversity, inclusion | `EPUB-C08`, `EPUB-NOTES` | | C-010 | EA | Existing documentation needs continual, dependency-aware maintenance | Practical; supported products | Staleness, escape defects, and user outcomes | Scheduled dependency review produces no benefit over reactive fixes | maintenance, atrophy | `EPUB-C10` | | C-011 | Q3P/EA | Measurement is useful when it reduces uncertainty for a decision | Methodological; business measures | Recorded decision, uncertainty, measure, and changed action | Measures that do not change decisions reliably improve outcomes | measurement | `EPUB-C11` | | C-012 | EA | Support deflection is hard to measure directly and requires bounded inference | Descriptive; support economics | Counterfactual study and sensitivity analysis | A direct, reliable method measures deflection without major assumptions | support deflection | `EPUB-C11` | | C-013 | EA | Tiger teams should be temporary responses to unplanned deadline failure | Prescriptive; urgent releases | Compare delivery, defects, burnout, and recurrence | Standing or repeated tiger teams outperform planned capacity without harm | tiger team | `EPUB-C12` | | C-014 | EA | Writers should verify primary sources and operate the product themselves | Methodological; research | Defect findings from hands-on checks versus interview-only work | Hands-on verification adds effort without finding meaningful differences | primary source, research | `EPUB-C13` | | C-015 | EA | Scenario content helps readers solve real problems across feature boundaries | Causal; end-to-end guidance | Task completion and transfer tests | Feature/reference paths produce equal or better performance | scenario, user goal | `EPUB-C14` | | C-016 | EA | Technical editing improves clarity, consistency, relevance, and access | Causal; drafts | Blind review and task tests before and after editing | Editing delays release without detectable reader benefit | technical editing | `EPUB-C15` | | C-017 | EA | Independent technical review is normally required for accurate docs | Prescriptive; product docs | Escaped defects by independent-review depth | Self-verified docs match independent review across risk classes | technical verification | `EPUB-C16` | | C-018 | EA | QA should execute complex or harmful procedures | Prescriptive; high-risk tasks | Defects found and prevented through clean-environment execution | QA execution finds no distinct errors over author and SME review | QA review | `EPUB-C16` | | C-019 | EA | Documentation tools should follow reader, author, process, portability, and support requirements | Methodological; tool selection | Total cost, migration, contributor flow, and reader outcomes | Feature-first or vendor-first selection consistently performs better | platform, portability | `EPUB-C17` | | C-020 | EA | Internal runbooks are part of the SaaS customer experience | Causal; service operations | Incident, consistency, recovery, and fleet-change data | Runbook quality has no relation to incident or service outcomes | runbook, SaaS | `EPUB-C25` | ### Evidence expectations pattern The book supplies abundant process detail, team examples, decision heuristics, and a few cited works. It supplies no comparative organizational dataset, task-test results, controlled before/after studies, staffing-cost model, or raw analytics. Claims about how to conduct work often have enough detail to test locally. Claims about business results, universal necessity, or causal effects exceed the book’s evidence. ### Claim dependency graph ```mermaid flowchart TD A["C-003 Audience evidence"] --> B["C-004 Learning objectives"] A --> C["C-007 Documentation decisions"] D["C-005 Closed feedback"] --> C C --> E["C-010 Maintenance priorities"] C --> F["C-019 Tool requirements"] G["C-001 Early product participation"] --> H["C-002 UX intervention"] G --> I["C-014 Primary-source research"] I --> J["C-017 Independent review"] J --> K["C-018 QA procedure tests"] B --> L["C-015 Scenario guidance"] H --> L E --> M["Reliable and useful documentation"] K --> M L --> M F --> M N["C-011 Decision-linked measurement"] --> D N --> E style A stroke-dasharray: 5 5 style N stroke-dasharray: 5 5 ``` **Load-bearing claims:** C-001, C-003, C-005, C-010, C-014, C-017, and C-011. The book’s practical system weakens if writers lack early access, audience evidence, a response path, upkeep capacity, primary-source access, independent review, or decision-linked measurement. **Claims that can fail independently:** The diversity/business-outcome claim (C-009), tiger-team model (C-013), and specific tool examples can fail without overturning the central cross-functional model. ### Claims mapped to questions - C-001, C-002 → Questions 1, 12, 21 - C-003, C-004, C-015 → Questions 2, 3, 18, 20 - C-005, C-006 → Questions 6, 7, 8, 10 - C-007, C-010, C-019 → Questions 11, 14, 16, 23 - C-009 → Questions 17–20 - C-011, C-012 → Questions 9, 24 - C-013 → Questions 12, 15 - C-014, C-017, C-018 → Questions 4, 13 - C-020 → Questions 11, 22, 23 --- ## Prompt 5 — quantitative rigor ### Policy Confidence percentages below encode judgment; they are not measured probabilities. A passage repeated across chapters remains one dependent source. Splunk examples support plausibility and implementation detail, not independent confirmation. Empirical claims without outcome data use qualitative updates. | Label | Range | |---|---:| | Very low | 0–20% | | Low | 21–40% | | Uncertain | 41–60% | | Moderate | 61–75% | | High | 76–90% | | Very high | 91–100% | ### Prior and posterior register Prompt 7 performs the evidence evaluation. This table records the planned update and the final result so the numerical judgment remains auditable. | Claim | Prior | Evidence considered | Dependence | Likelihood impact | Posterior | Main reason | |---|---:|---|---|---|---:|---| | C-001 Early participation | 78% | Repeated cross-functional mechanisms and later Splunk contribution workflow | High within book | Moderate increase | 84% | Mechanism is clear and locally testable | | C-003 Audience definitions | 72% | Detailed team case; no comparative task test | High | Small increase | 75% | Useful procedure, limited outcome evidence | | C-004 One objective per topic | 60% | Instructional-design adaptation and examples | Moderate | No meaningful update | 60% | “Every topic” is broader than evidence | | C-005 Closed feedback | 82% | Operational process and recurrence logic | High | Small increase | 86% | A feedback channel without response cannot repair content | | C-010 Continuous maintenance | 88% | Dependency examples and change mechanisms | High | Small increase | 90% | Product drift makes the need hard to avoid | | C-011 Decision-linked measurement | 90% | Hubbard framing, support-deflection cautions, Splunk example | Moderate | No meaningful update | 90% | Strong method, still judgment about usefulness | | C-014 Primary-source research | 84% | Worked examples and reproducible mechanism | High | Small increase | 88% | Direct execution can expose source disagreement | | C-017 Independent review | 85% | Detailed blind-spot model; no defect-rate data | High | No meaningful update | 85% | Strong rationale, universal wording remains broad | | C-018 QA tests risky procedures | 90% | Risk argument and role fit | High | Small increase | 92% | Failure cost justifies a strong default | | C-019 Requirements-first tools | 86% | Complete requirements frame and migration cautions | High | Small increase | 89% | Vendor names age; decision criteria persist | ### Calibration warnings | Risk | Severity | Why | |---|---|---| | False precision | High | The book reports counts and percentages without always showing collection or uncertainty | | Double-counted evidence | High | Many chapters draw on the same Splunk organization and culture | | Correlated sources | High | Team authors and internal examples are not independent witnesses | | Publication bias | Moderate | Successful practices are easier to remember and publish than failed attempts | | Survivorship bias | Moderate | A mature, resourced documentation team may hide prerequisites unavailable elsewhere | | Base-rate neglect | Moderate | Customer anecdotes and negative votes lack denominators for some conclusions | | Tiny samples | High | The Rule of Five can bound a median but cannot answer every decision or subgroup question | | Selection effects | High | Feedback contributors, support cases, and page visitors are self-selected | | Motivated estimates | Moderate | Documentation teams have reason to show business value and protect capacity | | Unavailable denominators | High | Customer-conversation and response-time claims lack full counts and populations | | Proxy measures | High | Page views, bounce, votes, and cases do not equal task success | | P-values as effect sizes | Not applicable | The book does not report significance tests | | Statistical significance as practical significance | Not applicable | The book does not report inferential statistics | ### Non-quantitative fallback Use **strongly decreases**, **moderately decreases**, **no meaningful update**, **moderately increases**, or **strongly increases confidence** when data cannot justify a number. Most transfer judgments in this note use this scale. --- ## Prompt 6 — analytical scaffold ### Chapter analysis slots | Anchor | Purpose and thesis | Evidence and example | Missing counterexample or question | Place in argument | |---|---|---|---|---| | C01 | Bound the book as broad, experience-based guidance | Team writing history | No test of whether identified literature gaps were real | Evidence contract | | C02 | Put writers inside iterative development | Scrum participation models | What if meeting load consumes writing capacity? | Access and timing | | C03 | Make audience assumptions explicit | Splunk audience-definition workshop | How were definitions validated with excluded or novice users? | Reader model | | C04 | Govern shared authorship | Wiki and multi-author examples | What contribution model works without paid curation? | Ownership | | C05 | Turn feedback into action | Response process and forums | How representative are commenters? | Learning loop | | C06 | Record decisions and iterate | Factors, data, expertise, ethos | What is the escalation path when business and user outcomes conflict? | Governance | | C07 | Limit third-party upkeep | Seven-option tree | Search-term advice can fail when vendors rename content | Scope control | | C08 | Build capacity and shared context | Hiring and team-change guidance | Diversity claim lacks internal outcome evidence | Organization | | C09 | Tie topics to observable outcomes | Matrix and worked objectives | One-objective rule may fragment complex reference content | Content model | | C10 | Maintain dependencies, not isolated pages | Cascading security-setting example | No cost model for proactive audits | Reliability | | C11 | Measure for a decision | Deflection uncertainty and vote/view correlation | Correlation still does not show task success | Steering | | C12 | Recover from deadline shock | Temporary parallel team | Repeated crisis use can hide structural understaffing | Exception handling | | C13 | Research primary sources and test | Hands-on procedure example | “Provoke a response with something wrong” risks trust | Truth finding | | C14 | Document end-to-end problems | Four-step scenario design | Scenario maintenance cost can be high | Outcome guidance | | C15 | Review usability and expression | Editing practices and checklist | Peer review power and language bias receive little attention | Clarity gate | | C16 | Independently verify technical truth | Role-specific review and QA | Public shaming can damage psychological safety | Accuracy gate | | C17 | Choose tools from requirements | Author, reader, portability, support checks | Named vendors and analytics examples age quickly | Infrastructure | | C18 | Join support knowledge to product docs | Top-issues meeting and rotations | Support’s crisis view can over-weight failures | Customer evidence | | C19 | Build peer relationships with engineers | Preparation, demos, shared tools | Writer credibility should not depend on performance of confidence | Source access | | C20 | Learn from field experience | Deployment and workflow feedback | Field reports remain indirect customer evidence | Transfer evidence | | C21 | Coordinate docs and marketing | Release-cycle collaboration | Business pressure can distort technical accuracy | External messaging | | C22 | Partner with product management | Shared outcome and complementary detail | No formal conflict-resolution model | Priorities | | C23 | Make remote work explicit and process-driven | Hand-offs and written communication | Burden falls on remote worker; office is treated as default | Distributed work | | C24 | Use explanation burden as a UX signal | Terminology and hidden-interaction examples | Complexity can be inherent, not a design defect | Product quality | | C25 | Treat internal docs as part of SaaS service | Runbooks, release enablement, fleet risk | “Good enough” conflicts with high-scale operational risk | Service operations | | C26 | Restate cross-functional purpose | Acknowledgments and invitation | No synthesis of conflicts among chapters | Closure | ### Argument spine 1. Software documentation is a product capability with customer outcomes. 2. Writers need explicit audience and goal models. 3. Those models guide scope, scenarios, priorities, and delivery choices. 4. Writers need early access to product decisions and primary sources. 5. Editing tests expression; independent review and QA test technical truth. 6. Feedback and measurement show where to revise. 7. Maintenance and internal operating docs keep the system reliable after release. 8. Cross-functional relationships make all earlier steps possible. **Weakest link:** The book moves from detailed Splunk experience to generalized organizational advice without comparative outcome evidence. The repair is to restate each practice as a testable default with prerequisites, owner, cost, and stop condition. ### Evidence ledger | ID | Claims | Type and source | Independent of authors? | Quality | Limits | |---|---|---|---|---|---| | E-01 | C-001–C-020 | Splunk team experience across chapters | No | C | Detailed but one organization | | E-02 | C-003 | Five-week audience-definition case | No | C | No user validation outcome | | E-03 | C-009 | McKinsey, HBR, MIT-linked diversity sources | Yes | C | Mixed definitions and business framing; authors do not appraise methods | | E-04 | C-004, C-015 | Dirksen, IBM guide, Baker | Yes | B | Supports instructional concepts, not every product-doc transfer | | E-05 | C-011 | Douglas Hubbard’s measurement model | Yes | B | Method cited; local applicability still requires a decision | | E-06 | C-012 | DB Kay support-deflection method | Yes | C | Authors expose unexplained probabilities | | E-07 | C-012 | Oracle support/revenue trend example | Yes | C | Observational and confounded; useful bounds, not exact causality | | E-08 | C-011 | Splunk negative-vote/page-view report | No | C | Prioritization example, not reader-success proof | | E-09 | C-016 | Splunk editing process and checklist | No | C | Rich implementation detail, no measured reader outcomes | | E-10 | C-019 | Ponydocs and Markdown/Git case | No | C | Honest tradeoffs, organization-specific upkeep capacity | Nine evidence families appear, but only five are external to the authors. None independently tests the full operating model. The strongest external material supports learning design and decision-focused measurement. The book itself supplies evidence against simplistic deflection measurement, feature-first tools, and unrestricted third-party coverage. ### Reading plan and Prompt 7 entry criteria - Read the evidence contract, audience, decisions, learning objectives, maintenance, measurement, research, editing, verification, tools, UX, and SaaS chapters at high attention. - Use cross-functional chapters when designing a specific interface or responsibility map. - Verify numerical response-time, business-impact, staffing, and feedback-volume claims externally before using them in policy. - Prompt 7 can begin because the source is complete, claims have stable IDs, evidence expectations and falsifiers exist, and evidence dependence is recorded. --- ## Prompt 7 — x-ray analysis and fair criticism ### Strongest reconstruction The authors’ strongest reasonable argument is not “copy Splunk.” It is this: 1. Users experience documentation as part of whether a product works for them. 2. A documentation team cannot create that experience from a finished feature and an engineering explanation alone. 3. Writers therefore need audience evidence, access to product decisions, hands-on product use, and regular contact with customer-facing functions. 4. Documentation requires separate checks for expression and technical truth. 5. Published content continues to change through product drift, customer evidence, and delivery technology. 6. Decisions and measures must connect to customer or business action. 7. The documentation organization succeeds by carrying context across product boundaries while maintaining a coherent information system. This reconstruction is more systematic than the alphabetical essay collection. It remains faithful because each step recurs across several chapters and the afterword names cross-functional product delivery as the unifying result. ### Claim evaluation | ID | Support | Grade | Strongest objection and counterexample | Current conclusion | |---|---|---:|---|---| | C-001 | Repeated mechanisms across Agile and partner chapters | B | Early access can become meeting overload without decision rights | Adopt with protected writing time and role boundaries | | C-002 | Concrete UX failure patterns | B | Explanation length can reflect domain complexity rather than bad design | Use as a diagnostic question, not proof of a defect | | C-003 | Detailed audience workshop and downstream uses | C | No outcome validation; categories can stereotype | Adopt only with research, expiry, and disconfirming cases | | C-004 | Instructional-design reasoning and examples | C | Reference and troubleshooting topics can serve several adjacent outcomes | Prefer one main outcome; allow justified secondary outcomes | | C-005 | Clear mechanism from report to correction and trust | B | Some feedback is abusive, low-value, or impossible to answer | Adopt an owned triage and response policy, not universal fulfillment | | C-006 | Direct-contact examples | C | Vocal customers are not representative | Triangulate direct contact with support, analytics, and research sampling | | C-007 | Complete decision framework | B | Process can exceed the value of a small reversible choice | Scale the record to decision cost and reversibility | | C-008 | Maintenance-risk decision tree | B | External docs can disappear or become inaccessible | Adopt with stable links, ownership, and periodic checks | | C-009 | External studies cited | D | “Diversity” categories and causal business effects vary; methods are not evaluated | Keep the moral and access case separate from performance promises | | C-010 | Strong dependency mechanisms and examples | B | Continuous maintenance competes with release work | Fund an explicit maintenance budget and risk tiers | | C-011 | Strong cited method and self-critical examples | B | A decision can still be framed to justify a preferred measure | Require precommitted decision rules and counter-metrics | | C-012 | Authors directly explain counterfactual uncertainty | B | Bounded estimates can still be useful | Treat deflection as a range and contribution claim, never a precise saving | | C-013 | Time-boxing, scope, and retrospective guidance | C | Crisis teams can reward bad planning and transfer burnout | Use once per surprise, record root cause, and prohibit routine recurrence | | C-014 | Reproducible hands-on research method | B | Test environments may differ from customer environments | Test directly, then cross-check with representative environments | | C-015 | Clear distinction from feature tours and tutorials | C | Scenarios are costly to keep current | Build them only for validated, durable, high-value workflows | | C-016 | Detailed editing functions and practices | C | No task-test outcome data | Adopt scaled editorial review; test high-value pages with users | | C-017 | Strong blind-spot and role-specialization argument | B | Low-risk changes may not justify a formal review | Default to independent review with explicit low-risk exceptions | | C-018 | Direct safety and reproducibility rationale | B | QA capacity can be scarce | Require execution for destructive, security, migration, and complex procedures | | C-019 | Broad, durable requirements model | B | A mature platform can reshape process beneficially | Select from outcomes and exit costs; let tools suggest, not dictate, process | | C-020 | Detailed runbook lifecycle and fleet-risk mechanism | B | Internal docs can fossilize unsafe practice | Adopt only with ownership, execution tests, revision triggers, and retirement | ### Grade distribution - A: 0 - B: 13 - C: 6 - D: 1 - F: 0 - N/A: 0 The distribution shows a strong practical handbook with substantial but bounded support. No claim earns A because the source does not provide direct independent tests of the full practice. The D falls on a broad causal diversity claim, not on the case for equitable participation itself. ### Biases and reasoning risks - **Selection and survivorship bias:** A mature Splunk team reports practices that fit the organization it helped build. This moderately limits transfer. - **Anecdotal generalization:** Detailed team examples often become second-person advice. This moderately limits certainty but does not erase the mechanisms. - **Correlation-causation risk:** Feedback, adoption, brand, support cost, and customer success can move together for many reasons. This strongly limits business-impact claims. - **Authority bias:** The team’s status and scale can make internal practice look like an industry baseline. This moderately affects staffing, tooling, and process advice. - **False universality:** “Always” and “every” appear in claims about learning objectives, review, and procedures. This is mainly a rhetorical overreach; risk-tiered exceptions repair it. - **Office-centered default:** Remote writers are asked to compensate for distance through visibility, travel, and constant responsiveness. This strongly limits the remote-work chapter’s current applicability. - **Fundamental attribution risk:** Review delays are sometimes framed as reviewer disposition rather than competing incentives, capacity, or unclear ownership. ### Counter-observations in the authors’ favor - They state that the book is not scholarship or a complete prescription (`EPUB-C01`). - They distinguish counting from measurement and criticize weak support-deflection assumptions (`EPUB-C11`). - They reject a universal writer-to-developer ratio and name work type and context switching as more important (`EPUB-C08`). - They warn that open contribution, content reuse, wiki links, and custom platforms all carry upkeep costs (`EPUB-C17`). - They say tiger teams are not a first resort and require a retrospective (`EPUB-C12`). - They acknowledge abusive feedback, poor reviewer fit, and the need to prioritize during team shrinkage. - They treat style-guide rules as subordinate to clear reading and usable content (`EPUB-C15`). ### Repairs | Original form | Repair | Faithful? | Cost | |---|---|---|---| | Every topic needs one learning objective | Every topic needs one stated main reader outcome; secondary outcomes need justification | Yes | Loses memorable certainty | | Independent review is always necessary | Use independent review by default; define low-risk exceptions and mandatory high-risk execution | Yes | Adds governance overhead | | Face-to-face is more productive | Choose the communication mode that preserves context, access, and decision trace for the people involved | Partly | Removes the book’s office preference | | Diverse teams drive business results | Build equitable participation because access and decision quality require missing perspectives; measure local outcomes separately | Yes | Gives up an easy ROI promise | | Feedback improves company success | An owned feedback loop can identify fixable friction; business effects remain contribution claims | Yes | Narrows causal language | | Use public shaming for late reviews | Escalate through pre-agreed ownership, due dates, and release risk; never use humiliation as a process | No | Rejects the tactic while preserving accountability | | Good enough is good enough in SaaS | Match review depth to failure scale; move fast only when changes are reversible and low-risk | Yes | Requires risk classification | ### Overall critique **What the book gets right:** Documentation is an evidence-carrying product function. The writers’ broad view helps teams notice that audience research, product design, support knowledge, procedure testing, maintenance, and internal service documentation are one connected system. The chapters on maintenance, measurement, research, editing, verification, and tool choice remain useful because they explain tradeoffs rather than naming one universal implementation. **What the book misses:** The system relies on substantial invisible coordination labor. It asks writers to monitor teams, answer customers, test products, shape UX, maintain content, train colleagues, manage projects, and preserve collective intelligence, but it offers little authority map, capacity budget, or refusal mechanism. Its disability-access discussion is much thinner than its audience and internationalization discussion. The remote-work model puts the burden of inclusion on the remote worker. AI-mediated retrieval and machine readership are absent because of publication date. **Conclusion:** Adopt the operating questions and high-risk quality gates. Treat organizational prescriptions as hypotheses. Reject coercive accountability, outcome claims without a counterfactual, and any expansion of writer duties without matching capacity and decision rights. --- ## Prompt 8 — context, lineage, and later developments ### Intellectual lineage ```mermaid flowchart LR A["Information development and task analysis"] --> F["The Product is Docs"] B["Agile and scrum"] --> F C["Instructional design"] --> F D["Every Page is Page One"] --> F E["Business measurement as uncertainty reduction"] --> F F --> G["Cross-functional documentation operations"] F --> H["Docs as code and open contribution"] F --> I["Product and developer experience practice"] J["AI and machine-readable sources"] -. convergent later context .-> H K["WCAG 2.2"] -. later standard .-> G ``` This map combines documented influences named by the book with later convergent context. It does not claim that later work was caused by this book. ### Context available to the authors - Agile and scrum had become standard organizing ideas, but implementation varied widely. - DITA, component content management, wikis, Markdown/Git, static delivery, and CI/CD competed as documentation systems. - SaaS moved documentation toward continuous release, shared-responsibility boundaries, runbooks, and fleet risk. - Every Page is Page One, instructional design, user-centered design, and task analysis shaped content planning. - Documentation teams faced pressure to show business value through support deflection, traffic, satisfaction, and reuse. ### Later context - The Write the Docs community records that its January 2020 book club discussed the first edition and that the second edition incorporated parts of that discussion. That history supports the preface’s account of community feedback: [Write the Docs book club](https://www.writethedocs.org/book-club/). - In 2023, Splunk opened its Observability Cloud documentation to GitHub-based community contribution. This is a later implementation of the book’s collaboration and docs-as-code direction, not proof that the model works everywhere: [Splunk community announcement](https://community.splunk.com/t5/Community-Blog/Moving-Splunk-Documentation-Forward-Opening-Our-Observability/ba-p/630810). - WCAG 2.2 became the current W3C Recommendation after the book’s publication and adds criteria such as consistent help, accessible authentication, focus visibility, and target size. A current documentation audit needs these concrete checks rather than the book’s general accessibility language: [WCAG 2.2](https://www.w3.org/TR/WCAG22/). - The vault’s later note [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]] adds machine readers to the audience model. Source format, navigation weight, structured metadata, and authoritative retrieval paths now affect both correctness and compute cost. - [[3. Resources/Readwise/Full Document Contents/Articles/Documentation and AI How to write right now Heidi Waterhouse LDX3 London 2025]] provides a convergent correction: automation can help with extraction, repetition, and structured variation, while human work remains necessary for context, intent, judgment, and empathy. ### Systems and incentives | Actor | Incentive | Contribution | Failure pressure | |---|---|---|---| | Users | Finish work safely | Feedback, task evidence | Time pressure, unequal access, incomplete context | | Writers | Create coherent and useful information | Research, synthesis, scope, coordination | Too many teams, weak authority, invisible labor | | Engineers | Ship correct software | Implementation facts, review, fixes | Feature deadlines and narrow component view | | QA | Prevent defects | Edge cases and procedure execution | Test capacity and late docs | | Product managers | Deliver customer and business outcomes | Priorities, audience, roadmap | Market deadlines and proxy goals | | UX | Create usable workflows | Research, prototypes, interaction design | Requirements and implementation constraints | | Support and field | Resolve real deployments | Failure patterns and workflows | Crisis selection bias and customer specificity | | Marketing | Explain value and release context | Message coordination | Overclaiming and launch pressure | | Documentation leaders | Maintain system and capacity | Staffing, standards, governance | Pressure to prove value with weak proxies | ### Historical judgment The book captures a transition from manual ownership to topic-level, collaborative, continuously delivered documentation. Its tool names are dated snapshots, but its requirements questions remain useful. Its office-centered assumptions aged faster than its audience, maintenance, verification, and feedback principles. Its human-only readership model now needs a second track for agents and answer systems. --- ## Prompt 9 — DEIB, multicultural, accessibility, and reading-level audit ### Inclusion strengths - The second edition adds an explicit section on creating and sustaining diverse teams (`EPUB-C08`). - The authors distinguish inclusion from assimilation and note that acknowledgment and belonging matter. - Several chapters ask writers to consider international audiences, localization, primary language, mobile access, and printable formats. - The editing checklist calls for short sentences, active voice, removal of idioms, meaningful headings, and image alternatives. - The team model values varied education and work histories rather than one credential pipeline. - The book addresses solo writers, small teams, team shrinkage, and users with different product skill levels. These are stated commitments and useful practices. The source does not show procedural protections that guarantee representation, accessible review, pay equity, or minority decision power after leadership changes. ### Exclusion and omission risks - **Disability:** Disability appears mainly in a list of diversity dimensions and an editorial checklist. The book does not cover assistive-technology testing, captions, keyboard access, cognitive load testing, accessible code examples, or disability-led research. - **Remote and global teams:** Chapter 23 frames a United States “home office” against teams in China, India, Russia, or Israel and places extra visibility, travel, availability, and deadline burdens on remote workers. That model can reinforce headquarters privilege. - **Class and organizational access:** Many practices assume paid staff, enterprise analytics, UX researchers, QA, customer access, training budgets, travel, and tool support. - **Commercial framing:** “Customer” dominates the model. Public-interest users, contributors, maintainers, students, and people who cannot pay receive little attention. - **Diversity argument:** Business-performance claims may instrumentalize people. “Diversity of thought” can blur structural exclusion tied to race, gender, disability, class, language, and geography. - **Psychological safety:** Public shaming and deliberately painful review meetings conflict with the collaborative editing model and can harm people with less status. - **Language:** The book focuses on English prose and translation readiness, not multilingual co-authoring or authority for local language communities. ### Multicultural transferability | Context | Transfer | Needed adaptation | |---|---|---| | Large commercial software company | High | Clarify authority, capacity, and current toolchain | | Small startup or solo writer | Moderate | Reduce meetings and artifacts; prioritize risk and customer tasks | | Open-source project | Moderate | Add contributor governance, volunteer boundaries, moderation, and public decision records | | WordPress contributor teams | Moderate | Account for distributed volunteers, release cycles, multilingual docs, and consensus authority | | Public-sector or regulated service | Moderate | Add legal obligations, records policy, procurement, and formal accessibility conformance | | Multilingual product | Low to moderate | Co-design with local-language users and plan terminology governance | | Low-bandwidth or mobile-first audience | Low to moderate | Offline access, small assets, printable flows, and constrained-device tests | | Safety-critical or destructive operations | Low without stronger controls | Formal validation, versioning, approvals, rollback, and audit trail | ### Accessibility audit of the EPUB | Area | Result | |---|---| | Text reflow | Generally good; text extracts cleanly | | Heading semantics | Chapter headings exist, but lower-level sections rely heavily on styled spans rather than semantic headings | | Image alternatives | Fail: all four informative figures have no `alt` attribute | | Figure equivalence | Partial: surrounding prose explains some decisions, but the learning matrix and analytics table are not fully reproduced | | Navigation | Partial: spine order works; NCX targets are malformed or overly dependent on conversion positions | | Language metadata | Pass: package declares English | | Accessibility metadata | Missing | | Color dependence | The learning-objective matrix uses color groupings; labels remain visible, but no text alternative explains the full grid | | Current standard | Not evaluated by the source against WCAG 2.2 or EPUB Accessibility 1.1 | ### Reading demand - **Syntax:** Grade 9–11 estimate. Sentences are usually direct, but several essays use long paragraphs and dense lists. - **Reference density:** Moderate. Readers need familiarity with Agile, scrum, SaaS, QA, UX, DITA, CI/CD, SEO, Jira, and content-management concepts. - **Navigation demand:** Low at chapter level because essays stand alone; moderate inside long chapters because many subheads are visual rather than semantic. - **Practical access:** Many recommendations require organizational authority, product access, test environments, analytics, and time from other roles. ### Supplementary perspectives - Disability-led documentation research and current WCAG/EPUB accessibility guidance - Documentation practice from multilingual and Global South teams - Volunteer and open-source documentation governance - Privacy-preserving analytics and bot-aware measurement - AI-assisted authoring, provenance, source retrieval, and machine-readable documentation - Labor research on invisible coordination, burnout, and authority without capacity --- ## Prompt 10 — notes pipeline and durable knowledge ### Fleeting notes - “The product is docs” only becomes operational when docs share release gates, product evidence, and upkeep ownership. - The book repeatedly expands the writer’s responsibilities; authority and capacity need an equal expansion. - Audience definitions should expire unless fresh evidence confirms them. - A documentation decision record needs a reversal trigger, not only a rationale. - Editorial review and technical execution are separate evidence channels. - Maintenance examples describe a dependency graph even though the book does not use that term. - The remote-work chapter reveals how quickly organizational advice can drift while process principles remain. - The artifact fails its own image-alt checklist. ### Literature notes - **LIT-01 — Documentation as product participation:** Early writer access supports research, UX intervention, review planning, and shared definitions of done (`C-001`, `C-002`; `EPUB-C02`, `EPUB-C24`). - **LIT-02 — Audience as a decision artifact:** Audience definitions matter only when they change scope, language, architecture, delivery, or testing (`C-003`; `EPUB-C03`). - **LIT-03 — Feedback must close:** Collection without acknowledgment, ownership, action, and validation is intake, not a learning loop (`C-005`; `EPUB-C05`). - **LIT-04 — Maintenance follows dependencies:** A small product change can require several documentation updates across owners and formats (`C-010`; `EPUB-C10`). - **LIT-05 — Measurement serves a choice:** Page views, votes, cases, and reuse counts gain meaning only through a decision and outcome (`C-011`, `C-012`; `EPUB-C11`). - **LIT-06 — Research requires direct contact with reality:** Writers should operate the product, compare sources, ask about consequences, and test likely mistakes (`C-014`; `EPUB-C13`). - **LIT-07 — Two quality gates:** Editing checks whether readers can understand; technical verification checks whether the content is true and executable (`C-016`–`C-018`; `EPUB-C15`, `EPUB-C16`). - **LIT-08 — Internal docs shape external service:** Runbooks and release-enablement docs change incident response and fleet consistency even when customers never see them (`C-020`; `EPUB-C25`). ### Permanent-note candidates #### Documentation earns product status through shared gates **Candidate filename:** `Documentation Earns Product Status Through Shared Release Gates.md` **Claim:** Calling docs a product has little effect unless documentation participates in requirements, definition of done, technical review, executable testing, release, and maintenance. **Confidence:** High. **Scope and conditions:** Applies to product documentation whose accuracy changes whether users can complete work. It weakens for low-risk commentary and fails when writers have no authority or capacity to participate in gates. **Sources:** LIT-01, LIT-07; C-001, C-017, C-018. #### A feedback channel is not a feedback loop **Candidate filename:** `A Feedback Channel Becomes a Loop Only After Disposition and Validation.md` **Claim:** Feedback improves a system only when someone acknowledges it, decides what it means, changes or declines something, and checks the result. **Confidence:** High. **Scope and conditions:** Applies to documentation and product feedback. It does not require implementing every request; an explained rejection can close the loop. **Sources:** LIT-03; C-005. Extends [[3. Resources/Permanent Notes/A Feedback Signal Not More Automation Is What Makes a System Self-Improving]]. #### Documentation maintenance is dependency management **Candidate filename:** `Documentation Maintenance Is Dependency Management.md` **Claim:** A content update is safe only after checking every topic, version, image, example, translation, and workflow that depends on the changed fact. **Confidence:** High. **Scope and conditions:** Strongest for versioned product and reference documentation. It weakens for self-contained essays. **Sources:** LIT-04; C-010. #### Documentation quality needs clarity and truth gates **Candidate filename:** `Documentation Quality Requires Separate Clarity and Truth Gates.md` **Claim:** Editorial clarity and technical correctness fail independently, so one review cannot stand in for both. **Confidence:** High. **Scope and conditions:** Applies when documents make executable or factual claims. The depth of each gate should follow failure risk. **Sources:** LIT-07; C-016–C-018. #### Documentation decisions need expiry and reversal rules **Candidate filename:** `Documentation Decisions Need Expiry and Reversal Rules.md` **Claim:** A rationale preserves why a decision was made; an expiry and reversal rule prevent yesterday’s constraints from becoming permanent policy. **Confidence:** Moderate. This is a system inference, not an explicit author claim. **Scope and conditions:** Applies to reversible scope, platform, audience, and maintenance choices. Legal record-retention decisions need formal governance. **Sources:** LIT-02, LIT-05; C-007, C-019. #### Documentation now serves people and machines differently No new note should be created. This conclusion already exists as [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]]. The book strengthens the human audience, context, and source-quality side; the existing note supplies the machine-retrieval side. ### Structure and connection decisions - Primary MOC: [[3. Resources/MOCs/Book Review Synthesis MOC]] - Adjacent MOC: [[3. Resources/MOCs/DevRel MOC]] - Direct connections: [[3. Resources/Readwise/Articles/Documentation Done Right A Developer’s Guide]], [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]], [[3. Resources/Permanent Notes/A Metric Is Vanity Only Against Your Own Outcome Data]], [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review]], [[3. Resources/Permanent Notes/Time-to-Hello-World Is the Critical Developer Experience Metric]] - No new permanent notes or reciprocal MOC links were created because the user required one file. Connection work remains explicit but incomplete. ### Attribution audit **Do not attribute to Gales or the Splunk Documentation Team:** - Documentation maintenance is a dependency graph. - Documentation decisions need expiry and reversal rules. - Product status depends on shared release gates. - Machine readers create a second documentation audience. - The book’s model expands invisible coordination labor. - Current WCAG 2.2, AI, privacy, and post-2020 remote-work comparisons. - Any confidence percentage, evidence grade, repair, experiment, or recommendation in this note. --- ## Prompt 11 — teaching pack ### Audience and prerequisites **Audience:** Technical writers, developer educators, product managers, engineers, QA, UX, support, and DevRel practitioners who share responsibility for product knowledge. **Prerequisites:** One real documentation set, one recent feature or support issue, access to a test environment, and permission to inspect the current review and release process. ### Learning objectives By the end, participants can: 1. Map a documentation outcome to a specific audience and task. 2. Identify where a writer needs access in the product lifecycle. 3. Separate editorial, SME, and executable verification. 4. turn one feedback signal into an owned disposition and validation step. 5. choose a measure by naming the decision it will change. 6. audit one content change for downstream dependencies. 7. reject a book recommendation when its prerequisites do not match the local team. ### Four-session sequence #### Session 1 — Documentation as product work - **Book argument:** Writers belong inside product development. - **Activity:** Draw the current feature-to-doc flow and mark where information arrives late. - **Case:** A feature reaches code freeze before the writer sees it. - **Misconception check:** Attending every meeting does not equal product influence. - **Assessment:** Propose one earlier input and one meeting or report to remove. #### Session 2 — Audience, objectives, and scenarios - **Book argument:** Explicit audiences and observable learning objectives improve scope. - **Activity:** Rewrite one feature-centered topic goal as a reader task and exit criterion. - **Case:** An “Admin” audience contains novices, experts, and several job roles. - **Misconception check:** A named persona is not evidence that a segment exists. - **Assessment:** Show the evidence source, excluded cases, and expiry date for the audience model. #### Session 3 — Quality and maintenance - **Book argument:** Editing, technical review, QA testing, and maintenance are distinct. - **Activity:** Run a procedure in a clean environment and log every hidden prerequisite. - **Case:** A security setting changes from optional to required in ten locations. - **Misconception check:** SME approval is not the same as successful execution. - **Assessment:** Produce a dependency list, reviewer roles, and release risk decision. #### Session 4 — Feedback and measurement - **Book argument:** Feedback and measurement matter when they change action. - **Activity:** Start with one pending decision, then select the smallest useful measure. - **Case:** A high-traffic topic has three negative votes while a low-traffic topic has four. - **Misconception check:** Neither vote count nor page views prove reader success. - **Assessment:** State the decision rule, confounders, and follow-up validation. ### Discussion questions - Which documentation duties require formal authority rather than personal credibility? - Where does the current process ask writers to absorb another team’s failure? - Which procedure could cause enough harm to require independent execution? - What feedback is systematically missing because the channel is inaccessible or unsafe? - When does “minimum documentation” reduce risk, and when does it transfer risk to the user? - Which metric would the team stop collecting if no decision depends on it? ### Facilitator cautions - Do not teach Splunk’s staffing, meeting, or tool practices as a universal baseline. - Disclose that no reader highlights or internal Splunk data were available. - Avoid asking participants to reveal disability, identity, burnout, or conflict experiences in public. - Do not present “public shaming” as an acceptable accountability tool. - Keep the live questions live: audience segmentation, one-objective topics, support deflection, and business causality remain context-dependent. - Do not attribute the permanent-note candidates or current-context corrections to the authors. ### Accessible and multicultural delivery - Supply materials before the session in accessible HTML or Markdown. - Describe diagrams in text and never rely on color alone. - Allow written, spoken, and asynchronous participation. - Use examples from commercial, open-source, public-sector, multilingual, and low-bandwidth contexts. - Let participants challenge the headquarters-centered model of remote work. - Replace timed performance with take-home application when processing or language access requires it. ### Assessment rubric | Dimension | Needs revision | Usable | Strong | |---|---|---|---| | Audience evidence | Assumed category | Named source | Triangulated, bounded, and expiring | | Outcome | Feature description | Reader task | Observable task and transfer condition | | Verification | Generic approval | Named reviewer | Role-specific review plus risk-based execution | | Feedback | Channel only | Owner and response | Disposition, validation, and recurrence check | | Measurement | Available count | Decision named | Decision rule, uncertainty, and counter-metric | | Access | General intention | Format checks | Disabled and multilingual users involved in testing | --- ## Prompt 12 — actions, PARA, experiments, and drift ### Action inventory #### Take - Add documentation to the definition of done for one bounded workflow, with explicit review and execution criteria. - Give every high-risk procedure an independent clean-environment test. - Record audience, intended task, source of truth, owner, and review date for high-value topics. - Convert feedback intake into a queue with acknowledgment, disposition, and validation states. - Audit dependency impact whenever a technical fact changes. - Start measurement requests by writing the decision that the result will change. #### Consider - A lightweight documentation decision record for high-cost or hard-to-reverse choices. - Scenario content for one validated, high-value, cross-feature task. - A temporary tiger team only for an unplanned, bounded release failure. - Public contribution only when review ownership, moderation, and upkeep capacity already exist. #### Avoid - Public shaming, humiliation, or deliberately painful meetings as review tactics. - Universal writer-to-developer or scrum-team ratios. - Treating page views, bounce, votes, or support cases as outcomes by themselves. - Turning one vocal customer or field story into an audience definition. - Expanding writer duties without authority, capacity, and stop rules. - Letting AI-generated prose bypass primary-source, editorial, and executable verification. > [!warning] Most likely misuse > The analysis could be used to justify making the writer responsible for every product information failure. The book’s cross-functional model works only when ownership, authority, staffing, and review duties are shared. ### PARA routing | Bucket | Material | Decision | |---|---|---| | Projects | None by default | A book review does not create a project without a live documentation target | | Areas | Technical writing, WordPress contributor education, DevRel | Use the review as an operating reference for recurring responsibilities | | Resources | Embedded literature notes, claim ledger, teaching pack | Keep inside this file under the one-file constraint | | Archives | This completed review | Preserve as the source-grounded session artifact | ### Reversible experiments | Experiment | Claims | Hypothesis | Action | Measure | Duration | Stop condition | Review date | |---|---|---|---|---|---|---|---| | One-workflow definition of done | C-001, C-017, C-018 | Earlier doc gates reduce late findings | Add doc scope, SME review, and clean execution to one feature | Late doc defects, rework, blocked days, task completion | 4 weeks | Meeting or review cost rises without fewer late findings | 2026-09-19 | | Five-user audience and task check | C-003, C-004, C-015 | A stated audience and outcome improve task success | Test one high-value topic with five representative users; revise once | Completion, errors, confidence, wrong-path starts | 3 weeks | Recruitment is unrepresentative or task risk is too high | 2026-09-12 | | Dependency-aware maintenance audit | C-010 | A source-fact change has more downstream effects than the initial ticket shows | Trace one changed setting across topics, versions, screenshots, examples, and links | Missed dependencies found; update effort; escape defects | 2 weeks | Scope expands beyond a safe bounded change | 2026-09-05 | | Feedback closure pilot | C-005, C-006 | Disposition and validation produce more useful learning than intake count | Process ten feedback items with owner, response, decision, and follow-up | Resolution time, recurrence, user confirmation, declined reasons | 4 weeks | Abuse, privacy, or workload exceeds the response policy | 2026-09-26 | | Measure-from-decision review | C-011, C-012 | Naming the decision removes low-value metrics | Review one dashboard; require a decision and action threshold for each metric | Metrics retired, decisions changed, collection cost | 2 weeks | A compliance requirement mandates the metric | 2026-09-05 | These are ordinary work-improvement pilots, not covert studies. Participants should know what is being tested and how results will be used. ### Decision rules - **Adopt:** The practice improves the named outcome twice without unacceptable access, delay, or labor cost. - **Adapt:** The mechanism helps but the role, cadence, sample, or gate is too heavy. - **Test further:** Results are mixed, the sample is narrow, or a confounder dominates. - **Reject:** The practice increases harm or cost without outcome gain. Revise the relevant candidate note rather than preserving it as doctrine. - **Defer:** The team lacks authority, environment access, representative participants, or a safe test case. ### Drift monitoring | Topic | What can change | Monitor | Cadence | Reassess | Early trigger | |---|---|---|---|---|---| | Accessibility | WCAG, EPUB standards, procurement rules, testing practice | W3C WAI and publishing standard bodies | Twice yearly | 2027-02-22 | New binding requirement or artifact format | | AI and machine readers | Retrieval formats, provenance, answer interfaces, crawler behavior | Source-format tests and vault AI-doc notes | Quarterly | 2026-11-22 | Search traffic or support path shifts materially | | Analytics | Privacy limits, bot traffic, vendor metrics | Analytics documentation and local traffic audit | Quarterly | 2026-11-22 | Human/machine traffic cannot be separated | | Remote work | Team distribution, async practice, office policy | Local team evidence | Twice yearly | 2027-02-22 | Process places unequal burden on location or time zone | | Tools | Vendor viability, portability, build support | Requirements and exit test, not feature news | At decision time | 2027-08-22 | Migration, ownership, or security risk changes | | SaaS operations | Release scale, shared responsibility, incident practice | Service owners and post-incident reviews | Quarterly | 2026-11-22 | Fleet incident or responsibility-boundary change | **Claims unlikely to drift:** Readers need context; factual procedures require verification; content changes have dependencies; feedback needs disposition; measurement should serve decisions. Their implementation can drift even when the principle remains stable. --- ## Prompt 13 — visual thinking pack ### Visual 1 — documentation operating loop **Purpose:** Show the repeated flow from evidence to maintained product knowledge. ```mermaid flowchart LR A["Audience and user goal"] --> B["Product access and research"] B --> C["Documentation decision"] C --> D["Draft or revise"] D --> E["Editorial review"] E --> F["Technical review"] F --> G["Executable test when risk warrants"] G --> H["Publish"] H --> I["Feedback and task evidence"] I --> J["Maintenance and dependency audit"] J --> C K["Missing reader-emphasis evidence"] -.-> A style K stroke-dasharray: 5 5 ``` - **Claims:** C-003–C-007, C-010, C-014, C-016–C-018 - **Source anchors:** `EPUB-C03`, `C05`, `C06`, `C10`, `C13`, `C15`, `C16` - **Layout:** Horizontal loop with the uncertainty node below the audience input. ### Visual 2 — cross-functional ownership map **Purpose:** Prevent “cross-functional” from becoming “the writer owns everything.” ```mermaid flowchart TB U["Users"] -->|tasks and feedback| W["Writer / documentation system"] PM["Product management"] -->|outcomes and priorities| W ENG["Engineering"] -->|implementation and fixes| W QA["QA"] -->|execution and edge cases| W UX["UX"] -->|research and design| W SUP["Support and field"] -->|real deployments and failures| W W -->|coherent guidance and friction evidence| U W -->|documentation defects and design findings| ENG W -->|audience and task evidence| PM W -->|explanation burden| UX W -->|testable procedures| QA L["Documentation leadership"] -->|capacity, standards, escalation| W R["Shared release governance"] --- PM R --- ENG R --- QA R --- W ``` - **Claims:** C-001, C-002, C-005, C-006, C-017, C-018 - **Uncertainty:** The source describes interfaces more fully than formal authority or escalation. - **Layout:** Writer at center, shared governance below, users above. ### Visual 3 — evidence-strength map **Purpose:** Separate implementation detail from transfer confidence. ```mermaid flowchart LR A["Rich Splunk process detail"] --> B["High implementation usefulness"] A --> C["One-organization dependence"] D["Selected external books and cases"] --> E["Moderate conceptual support"] C --> F["Limited transfer confidence"] E --> F G["No comparative outcome dataset"] -.-> F F --> H["Treat practices as testable defaults"] style G stroke-dasharray: 5 5 ``` - **Claims:** All; especially C-003, C-009, C-011, C-016–C-020 - **Source anchors:** `EPUB-C01`, `EPUB-NOTES` ### Visual 4 — risk-based quality decision tree **Purpose:** Repair the book’s universal review language without weakening high-risk controls. ```mermaid flowchart TD A["Content change"] --> B{"Can an error cause security, data, money, access, or major time harm?"} B -->|Yes| C["Independent SME review plus clean execution"] B -->|No| D{"Is the claim new, technical, or hard to reverse?"} D -->|Yes| E["Independent review; sample execution"] D -->|No| F["Peer or automated check under explicit exception"] C --> G["Record result and owner"] E --> G F --> G G --> H["Publish and monitor"] ``` - **Claims:** C-016–C-018 - **Source anchors:** `EPUB-C15`, `EPUB-C16` - **Uncertainty:** Local risk policy determines thresholds. ### Excalidraw-ready book map Use a landscape canvas with five columns: 1. **Know the reader:** Audience, feedback, field, support. 2. **Join product work:** Agile, decisions, engineers, PM, UX, marketing. 3. **Design guidance:** Learning objectives, scenarios, third-party scope. 4. **Prove quality:** Research, editing, technical verification. 5. **Operate over time:** Maintenance, measurement, tools, SaaS, teams. Place “Documentation as product capability” across the top. Put “Authority and capacity” as a red dashed bar under all columns because the source under-specifies it. Put “System-selected emphasis; no reader highlights” in a gray dashed box outside the map. Connect feedback to every column with a return arrow. ### Visuals omitted - **Formal causal-loop diagram:** Omitted because the book does not validate causal strengths or delays; a loop could imply more certainty than the evidence supports. - **Detailed timeline:** Omitted because the book is thematic, not historical. Prompt 8’s lineage map captures the useful sequence. - **Terminology map:** Omitted because the controlled-vocabulary table shows distinctions more clearly. - **Comparison matrix:** Omitted as a separate diagram because Prompt 9’s transfer table and Prompt 7’s grades already perform that work. - **Standalone action map:** Omitted because Prompt 12’s experiments include decision rules, dates, and stop conditions. --- ## Final synthesis ### The book in one sentence *The Product is Docs* turns technical documentation from a writing output into a cross-functional operating system, with unusually practical guidance and unusually limited evidence for how well that system transfers beyond Splunk. ### What changed in the priors - **Strengthened:** Early product access, closed feedback, dependency-aware maintenance, primary-source research, independent review, QA execution for high-risk procedures, and requirements-first tool selection. - **Qualified:** Audience definitions, one learning objective per topic, scenarios, direct customer contact, and open contribution all need local validation and limits. - **Rejected:** Public shaming and deliberately painful review meetings as accountability methods. - **Held as unresolved:** Exact support-deflection value, business outcomes attributed to documentation, numeric response rules, and performance gains attributed to diversity. - **Added:** Documentation practices need authority, capacity, expiry, and stop conditions; machine readers now belong in the audience and delivery model. ### Best next move Choose one high-risk or high-friction procedure. Name its audience and real-world task, trace its sources and dependencies, run it in a clean environment, have another person test the result, and record the feedback disposition. This exercises the book’s strongest system without creating a new program or dashboard. --- ## Session completion check ### Prompt status | Prompt | Status | Adaptation | |---|---|---| | 0 | Complete | Full local EPUB replaced Readwise; system-selected anchors | | 1 | Complete | Missing reader inputs labeled as system assumptions | | 2 | Complete | All 26 chapters mapped and covered | | 3 | Complete | Sixteen-term controlled vocabulary and category watch | | 4 | Complete | Twenty claims, expectations, falsifiers, and dependencies | | 5 | Complete | Dependence-aware confidence policy and ten updates | | 6 | Complete | Twenty-six chapter slots, argument spine, and evidence ledger | | 7 | Complete | Fair reconstruction, twenty claim grades, objections, and repairs | | 8 | Complete | Intellectual lineage, systems context, and later developments | | 9 | Complete | DEIB, multicultural transfer, artifact access, and reading demand | | 10 | Complete | Notes and candidates embedded; no extra files | | 11 | Complete | Four-session teaching pack and assessment rubric | | 12 | Complete | Actions, PARA, five experiments, decision rules, and drift | | 13 | Complete | Four Mermaid models and Excalidraw-ready map | ### Missing evidence ranked by consequence 1. **High:** Reader highlights, questions, agreement, disagreement, and intended use. 2. **High:** Comparative outcome data across documentation teams and organization types. 3. **High:** Raw task-test, defect, support, staffing, and customer-feedback data behind Splunk practices. 4. **Medium:** Disabled and multilingual user research, assistive-technology testing, and current accessibility conformance. 5. **Medium:** Cost and capacity data for the cross-functional duties assigned to writers. 6. **Medium:** Evidence from small teams, open source, public-sector work, and low-resource settings. ### Assumptions made - Purpose was inferred as practical evaluation for current technical documentation, WordPress, and DevRel work. - Reading depth was set to analytical because the request supplied the complete Prompt 0–13 chain and required one file of everything processed. - The current book-review archive pattern controls file shape over the older two-file skill default. - All selected passages and hotspots are system choices, not reader emphasis. - The plain-text extraction count is the least markup-inflated word count. - Current context was limited to sources that materially change interpretation. ### Contradictions resolved - The standard workflow can create separate review, session, source, and visual files. The user’s one-file instruction controls, so all outputs remain here. - Prompt 10 requests separate permanent notes and reciprocal MOC links. Those changes would violate the single-file boundary, so candidates and target links are embedded and the incomplete reciprocal state is disclosed. - Prompt 0 normally begins with Readwise. The validated local EPUB is Layer 1, with loss of reader emphasis recorded. - The book’s universal review language is repaired into risk-based defaults; high-risk execution remains mandatory. ### Final state - Executed prompts: 0–13. - Usable prompt outputs: 0–13. - Skipped prompts: none. - Partial failures: none; source and personalization limits are documented. - Remaining prompts: none. - Next prompt: none. - Session status: complete with documented source limits. ### Session record ```yaml source_of_truth: "6. Templates/Books/Work the Book.md" source_spec_version: 2 executed_prompts: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13] skipped_prompts: [] remaining_prompts: [] output_files: - "4. Archives/Book reviews/The Product is Docs.md" status: "complete_with_documented_source_limits" ``` ## Sources ### Primary source - Gales, Christopher, and the Splunk Documentation Team. *The Product is Docs: Writing Technical Documentation in a Product Development Group*. Second edition, independently published, 2020. Local EPUB, SHA-256 `803fa126522462048ffcca6b31a4fd895618524779c351cdac2a96fe0dffae0a`. ### Publication and later context - [Google Books bibliographic record](https://books.google.com/books/about/The_Product_is_Docs.html?id=-KnQzgEACAAJ) - [Write the Docs book club record](https://www.writethedocs.org/book-club/) - [Splunk: Moving Observability Cloud docs to community contribution](https://community.splunk.com/t5/Community-Blog/Moving-Splunk-Documentation-Forward-Opening-Our-Observability/ba-p/630810) - [W3C Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) ### Vault context - [[3. Resources/Readwise/Articles/Documentation Done Right A Developer’s Guide]] - [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]] - [[3. Resources/Readwise/Full Document Contents/Articles/Documentation and AI How to write right now Heidi Waterhouse LDX3 London 2025]] - [[3. Resources/Permanent Notes/A Metric Is Vanity Only Against Your Own Outcome Data]] - [[3. Resources/Permanent Notes/A Feedback Signal Not More Automation Is What Makes a System Self-Improving]] - [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review]] - [[3. Resources/Permanent Notes/Time-to-Hello-World Is the Critical Developer Experience Metric]]