# Docs for Developers *An Engineer’s Field Guide to Technical Writing · second edition · Jared Bhatti, Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse · Apress, 2026* This field guide earns its place in a documentation workflow through its task research, four editing passes, publishing checks, and maintenance decisions. Its central test is whether a reader can accomplish a goal. Treat its metrics as diagnostic signals, its large-company examples as cases, and its AI recommendations as proposals that need tool-specific verification. Several categorical claims exceed their evidence; the EPUB itself contains inaccurate image descriptions and an impossible date in an example response. **Recommended use — system assessment:** apply the research → draft → test → revise loop to one existing developer task. Start with a friction log and a complete quickstart, then measure completion and failures. The book supplies practices to test; it doesn't establish a universal productivity effect or prove that a documentation tool guarantees user success. **Navigation:** [[#Prompt 0 — Sources and ingestion|Sources]] · [[#Prompt 4 — Claims and dependencies|32 claims]] · [[#Prompt 6 — Chapter analysis and evidence ledger|Chapter analysis]] · [[#Prompt 7 — Evaluation and fair criticism|Evaluation]] · [[#Prompt 9 — Inclusion and accessibility audit|Accessibility]] · [[#Prompt 11 — Teaching pack|Teaching]] · [[#Prompt 12 — Actions and experiments|Actions]] · [[#Prompt 13 — Visual thinking pack|Visuals]] · [[#Layer 1 — Readwise highlights|All highlights]] · [[#Session record and completion audit|Session audit]] ## Prompt 0 — Sources and ingestion ### Source record and edition boundary | Field | Verified value | | --- | --- | | Primary source | The local EPUB supplied with this request; full absolute path appears in front matter. | | Edition | Second edition. Copyright page names 2021 and 2026; preface identifies the revised edition. | | Publisher and identifiers | Apress; ebook ISBN 979-8-8688-2509-5; print ISBN 979-8-8688-2508-8; DOI 10.1007/979-8-8688-2509-5. | | Publication | Ebook June 15, 2026; print June 16, 2026. The filename's June 16 date isn't the ebook publication date. [Publisher record](https://link.springer.com/book/10.1007/979-8-8688-2509-5). | | Package | EPUB 3; 88 ZIP entries; 27 spine resources, including cover, 10 front-matter files, 11 chapters, and 5 back-matter files. ZIP integrity check passes. | | Extent | Publisher: XXVII + 251 pages. Approximately 51,000 words in extracted spine body text; this is an extraction count, not a reading-speed estimate. | | Navigation | All 527 local navigation links and 257 NCX links resolve to existing resources and anchors. This verifies destinations, not assistive-technology usability. | | Source fingerprint | SHA-256 `e794b6cb78d7f675b2727456ccb5dfd62858dabcc5e5f761615a4ea4d103b8f9`. | | Earlier source | Readwise book 22380269, Kindle ASIN B09HLZGWKT; highlights from 2022 and 2024 predate this edition. [Readwise record](https://readwise.io/bookreview/22380269). | | Existing import | [[3. Resources/Readwise/Books/Docs for Developers|Existing Readwise import]]; retained without modification. | | Existing review | This canonical filename already held a short review dated 2026-03-01. Its complete original text and metadata remain in the legacy appendix. | The current author credit uses **Sarah Corleissen**, as printed in this edition. The earlier review and Kindle metadata use a different author-name form; the archived originals preserve that provenance. The older `Read` status does not establish that Courtney has finished the second edition. This session records completed system analysis, with the reader's second-edition reading status unknown. ### Coverage and attribution **Read:** all 11 chapters, appendices A–C, foreword, introduction, preface, acknowledgments, and author material through the full extracted text, with targeted returns to original XHTML for quotations and findings. The table of contents, index, and 52 bibliography entries were inspected; the bibliography's underlying works were not all read. All 22 numbered figures were visually inspected in contact sheets, with targeted comparison to their native alt text. Code and tables were read as source material; the fictional Corg.ly service was not called. **External checking:** publisher metadata; OpenAI's original launch announcement; official AGENTS.md format guidance; Google's sitemap and URL guidance; W3C image guidance; Nielsen's original 28% calculation; the institutional abstract of the 13-millisecond image study. Learning-styles research was located, but full-paper retrieval did not provide a readable paper in this session; its methods and results aren't independently audited here. **Named vault context inspected:** the existing review and Readwise import, [[4. Archives/Book reviews/The Product is Docs|The Product is Docs]], [[4. Archives/Book reviews/Letting Go of the Words|Letting Go of the Words]], [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure|Documentation Is Dual-Audience Infrastructure]], and [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review|Friction Logging Is the DevRel Equivalent of Code Review]]. These are comparisons with existing notes, not fresh readings of those books or an audit of the whole vault. Attribution labels used below: - **Author says:** explicit claim or faithful paraphrase from the supplied edition. - **Author implies:** an inference about the book's reasoning, identified as such. - **Third party:** a study, quoted speaker, or source the book invokes; quotation doesn't make it the authors' original finding. - **Reader evidence:** existing highlights, tags, or supplied instructions. A highlight records attention, not agreement. - **We infer / We conclude:** this session's system analysis, not Courtney's personal belief. - **Still uncertain:** a missing source, untested mechanism, or unresolved scope question. Source locators use native EPUB identifiers. `EPUB-C04#Par25` means `OEBPS/html/505277_2_En_4_Chapter.xhtml#Par25`; chapter numbers map the same way throughout. `EPUB-PREF`, `EPUB-INTRO`, and `EPUB-FOREWORD` mean `Frontmatter_005.xhtml`, `Frontmatter_006.xhtml`, and `Frontmatter_003.xhtml`. `EPUB-A`, `EPUB-B`, `EPUB-C`, and `EPUB-BIB` mean `Backmatter_001.xhtml` through `Backmatter_004.xhtml`. These paths are inside the supplied archive. Printed pages supplement anchors; Kindle locations aren't interchangeable with them. ### Readwise ingestion summary and highlight index The exact book-ID retrieval returned **76 records with no next page**. All 76 have location values and blue color. All highlight notes and the book's document note are empty. Seventy-five records carry July 10, 2022 timestamps; one carries August 20, 2024. The book tag is `Dev Work`; RW-440527355 also has `favorite`. Stable IDs below retain the original Readwise ID after `RW-`. Two prose-linter records, RW-440527359 at location 3013 and RW-760358744 at location 3002, differ in spacing and timestamps. They represent **one normalized passage and two source records**: 75 normalized passages, 76 preserved records. Neither timestamp nor location is discarded. Repeated concepts elsewhere remain distinct passages. No exact second-edition Reader record was verified; a noisy search doesn't prove that none exists. Chapter assignment below is **system-inferred for the older Kindle highlights**, using location order and topics that match the current chapter sequence. It isn't Readwise-supplied chapter metadata. Density describes this reader's saved material, not the book's emphasis or chapter quality. | Provisional chapter group | Kindle locations | Records | Share | | --- | --- | ---: | ---: | | 1. Audience | 579–781 | 10 | 13.2% | | 2. Planning | 862–1044 | 8 | 10.5% | | 3. Drafting | 1158–1234 | 2 | 2.6% | | 4. Editing | 1420–1561 | 7 | 9.2% | | 5. Code samples | 1644–1791 | 3 | 3.9% | | 6. Visuals | 1851–1917 | 4 | 5.3% | | 7. Publishing | 2098–2157 | 4 | 5.3% | | 8. Feedback | 2239–2334 | 5 | 6.6% | | 9. Quality | 2424–2628 | 14 | 18.4% | | 10. Organization | 2728–2860 | 8 | 10.5% | | 11. Maintenance | 2926–3057 | 8 | 10.5% | | Additional resources | 3116–3184 | 3 | 3.9% | Case-insensitive substring counts across the 76 records: `user` appears in 30, `code` in 15, `quality` and `feedback` in 4 each, `accuracy` in 3, and `friction` in 2. These counts include word variants and the near duplicate. Google and Corg.ly each appear in one record; organization-name repetition doesn't dominate this saved set. Recurring structures include checklists, goal/result language, content types, and maintenance decisions. The repeated linter passage provides no independent corroboration. | Inferred cluster | Span | Topics and rationale | Representative records | | --- | --- | --- | --- | | Cluster A — Discover and plan | 579–1234 | Research becomes a user task, document type, and draft outline. | RW-440527296, RW-440527299, RW-440527300, RW-440527303, RW-440527309 | | Cluster B — Make the content work | 1420–1917 | Editing, runnable examples, and visuals test the draft's usability. | RW-440527311, RW-440527315, RW-440527317, RW-440527318, RW-440527322 | | Cluster C — Release and learn | 2098–2628 | Publishing exposes content to users; feedback and metrics guide changes. | RW-440527326, RW-440527332, RW-440527335, RW-440527344, RW-440527345 | | Cluster D — Organize and maintain | 2728–3057 | Navigation and ownership preserve usefulness as the product changes. | RW-440527348, RW-440527353, RW-440527355, RW-440527356, RW-440527360 | | Cluster E — Continue learning | 3116–3184 | Courses, checklists, and practitioner community extend the book. | RW-440527362, RW-440527363, RW-440527364 | These clusters summarize the older highlight set. The actual second-edition table of contents, not the clusters, controls the chapter analysis. All source highlights appear in [[#Layer 1 — Readwise highlights]]. ## Prompt 1 — Contract, baselines, questions, and priors ### Reading contract **Reader-provided:** process the supplied book through Prompts 0–13 and save one consolidated note in the existing reviews folder. No current project, personal prior probabilities, deadline, or new-edition highlights were supplied. **System-inferred purpose:** evaluate methods you could use in developer documentation, technical writing, and DevRel. The existing vault notes support that application; this isn't a claim about your present employer, assignment, or preferences beyond the request. Success means the note covers every chapter, evaluates a bounded set of major claims, preserves the source record, distinguishes transferable methods from overclaims, and offers a reversible test on an existing document. A method should earn adoption through observed task completion, fewer relevant errors, or a maintainable review cost. Disconfirming evidence includes failed fresh-user trials, excluded users, regressions hidden by aggregate metrics, or verification effort greater than the benefit. The book can't establish effects for your users without local observation. Its fictional product demonstrates a workflow; it doesn't supply a deployed-system experiment. Industry anecdotes don't establish universal ROI. This session doesn't test every code listing, reproduce every cited study, certify accessibility, or assess the authors' current tool affiliations. ### Baselines, incentives, and uncertainty Your highlights establish past attention to quality, maintenance, and user impact; the favorite on RW-440527355 supports prioritizing impact analysis. They don't establish current agreement. The old review's personal-reflection section may contain prior system writing; authorship is unverified. No motive, identity, financial incentive, or private belief is inferred for you. **System susceptibility:** a checklist can look complete before a user succeeds; familiar docs-as-code practices can receive too much credit; source errors can tempt an unfair rejection of the whole book. Countermeasures here are claim-by-claim grading, concrete counterexamples, and separate tests of text accuracy, runtime behavior, and human outcomes. The authors' practitioner backgrounds explain their examples; they don't validate every number or recommendation. ### Open questions inventory | ID | Category | Question and disposition | | --- | --- | --- | | Q01 | Definitions | What makes a document good? Purpose fulfilled; distinguish functional from structural quality. C-015. | | Q02 | Definitions | How do tutorials, how-to guides, and reference differ? By reader need, with boundary cases. C-004. | | Q03 | Mechanisms | How does research change what gets written? Goals and constraints become task scope. C-001. | | Q04 | Mechanisms | When should a friction log produce a product fix? When the barrier is product behavior, not missing explanation. C-003. | | Q05 | Evidence | Does a 3–5-person round represent the whole audience? No; coverage depends on recruitment and purpose. C-002. | | Q06 | Evidence | Do four passes outperform another workflow? Plausible separation of concerns; comparative effect remains unmeasured. C-007. | | Q07 | Evidence | What does successful visual processing prove about documentation? Less than the chapter's numerical framing suggests. C-010. | | Q08 | Context | Which practices depend on staff, release cadence, or hosting? Reviews, councils, sandboxes, and telemetry. C-013, C-024. | | Q09 | Context | Is this a 2021 book with new material or an independently tested 2026 method? Revised field guide; no outcome evaluation supplied. C-028–C-032. | | Q10 | Application | What should you try first? One bounded friction log and task-focused revision. C-003, C-006. | | Q11 | Application | How do you verify examples without a live service? Validate syntax, fixtures, assumptions, and declared behavior separately. C-009. | | Q12 | Counterarguments | Must a person proposing criticism also know a solution? No; valid reports can lack remedies. C-008. | | Q13 | Counterarguments | Does simpler language mean less technical detail? No; retain needed precision and define terms. C-016. | | Q14 | Failure modes | Can passing linters conceal task failure? Yes; lint checks only its configured rules. C-025. | | Q15 | Failure modes | Does a shared release date prove documentation matches behavior? No; coverage and tests still matter. C-023. | | Q16 | Failure modes | When can traffic or support counts mislead? When exposure, task, product, or user mix changes. C-017, C-018. | | Q17 | Inclusion | Who is excluded by recruiting only vocal users or customers? Nonusers, people who abandoned, and some disabled users. C-001, C-014. | | Q18 | Multicultural use | Which navigation and examples assume English or left-to-right reading? Headings, scanning patterns, idioms, personas, and diagrams. C-006, C-021. | | Q19 | Accessibility | Does nonempty alt text convey the same information? The EPUB provides direct counterexamples. C-012. | | Q20 | Accessibility | Does rejecting learning-style matching justify one delivery format? No; access requirements and preference-matching theories differ. C-011. | | Q21 | Unanswered | Do crawler hints guarantee indexing or correct AI answers? No guarantee is established; sitemap claim is contradicted. C-019, C-020. | | Q22 | Unanswered | When is deletion justified despite low usage? Check supported tasks and offer migration or replacement. C-027. | | Q23 | Unanswered | Which AI tasks save net effort after review? Local comparison remains necessary. C-028–C-030. | | Q24 | Credibility | Which edition facts or current-tool statements need correction? Launch year, indexing assurances, capability absolutes. C-019, C-020, C-030, C-031, C-032. | ### Priors seed table These are **retrospective system starting positions for the analysis**, not Courtney's beliefs or preregistered forecasts. Reading and drafting happened within one session; the update table documents reasoning rather than calibrated prediction performance. | Claim | Initial position | Confidence | Reason for starting position | Evidence needed | | --- | --- | --- | --- | --- | | C-001 | Research can reveal missing context. | Moderate | Reader goals constrain needed information. | Observed goal/task mismatch followed by a relevant revision. | | C-003 | A bounded friction log can expose barriers. | Moderate | Expected and actual steps are directly comparable. | Reproducible obstacle with environment recorded. | | C-007 | Separate editing passes help find different defects. | Moderate | Accuracy and clarity involve different checks. | Comparable drafts and reviewer effort/outcomes. | | C-009 | Runnable examples need functional tests. | High | Syntax alone can't establish promised behavior. | Successful and failing controls in a declared environment. | | C-010 | Relevant visuals can aid some tasks. | Moderate | Spatial relations can be shown directly. | Task-specific comparison, not recognition speed alone. | | C-017 | TTHW is informative but incomplete. | Moderate | Timing includes setup and prior knowledge. | Completion, failure, and timing by comparable cohort. | | C-018 | Raw traffic isn't a quality measure by itself. | High | Visits have multiple causes. | Denominators and paired qualitative evidence. | | C-020 | An AGENTS.md file may help compatible agents. | Uncertain | Consumption depends on the runtime and retrieval path. | Confirmed file loading and answer/task comparison. | | C-023 | Coordinated releases reduce mismatch risk. | Moderate | Timing removes one route to staleness. | Content coverage and behavior verified at release. | | C-029 | AI assistance may save some drafting effort. | Uncertain | Review can erase generation savings. | Total effort, factual errors, and task outcomes compared. | **One-year drift risks:** AI model capabilities and context-file loaders; support and pricing for named services; search behavior; examples tied to product versions; release policies; documentation-hosting analytics; accessibility tooling. The goal-first and provenance principles depend less on current tooling. No legal interpretation is supplied: the book's mentions of privacy and copyright require context-specific checking before operational use. ## Prompt 2 — Inspectional reading ### Book map All mappings have high confidence because the EPUB supplies chapter titles and complete chapter text. Appendix B is a separate AI treatment, not chapter 12. | Source / printed pages | Purpose and central topic | Contribution and available evidence | | --- | --- | --- | | Foreword, preface, introduction | Frame writing as a practice developers can learn. | Practitioner narrative; edition changes; fictional Corg.ly demonstration. | | 1. Understanding Your Audience, 1–22 | Discover users' goals, knowledge, and constraints. | Interviews, personas, journeys, friction logs; foundation for scope. | | 2. Planning Your Documentation, 23–48 | Match tasks to content types and plan coverage. | READMEs, quickstarts, concepts, procedures, reference; plan templates. | | 3. Drafting Documentation, 49–70 | Turn a plan into an outline and draft. | Corg.ly outlines, headings, procedures, callouts; task structure. | | 4. Editing Documentation, 71–85 | Test accuracy, completeness, organization, and language. | Four passes, review roles, feedback practices; revision method. | | 5. Integrating Code Samples, 87–104 | Make samples explained and usable. | Executable/explanatory distinction and listings; claims can be checked. | | 6. Adding Visual Content, 105–126 | Choose, explain, and maintain visuals. | Screenshots, diagrams, videos, accessibility; mixed research support. | | 7. Publishing Documentation, 127–137 | Define and test a release path. | Approval and release checklist; small-team and larger-team variants. | | 8. Gathering and Integrating Feedback, 139–153 | Collect, triage, and respond to problems. | Feedback channels, surveys, issue templates, priorities. | | 9. Measuring Documentation Quality, 155–176 | Connect function and structure to measures. | Quality categories, TTHW, web/support metrics; denominator cautions. | | 10. Organizing Documentation, 177–194 | Build and revise information architecture. | Sequential, hierarchical, and web structures; inventories and migration. | | 11. Maintaining Documentation, 195–210 | Keep docs aligned with a changing product. | Impact analysis, ownership, automation, versioning, deprecation. | | A. When to Hire an Expert, 211–214 | Identify work that benefits from specialist help. | Scope and staffing advice; no hiring-outcome study. | | B. AI Documentation, 215–226 | Explain AI uses and editorial responsibility. | Tool categories, review, content preparation; capability claims age quickly. | | C. Additional Resources, 227–238 | Offer courses, communities, frameworks, and books. | Discovery list; inclusion doesn't establish effectiveness. | | Bibliography, 239–244; index, 245–251 | Attribute sources and aid navigation. | 52 bibliography entries; source trail, not independent corroboration itself. | ### Central project and provisional summary **Problem:** developers know their software but may not know what another person needs to use it. **Answer:** treat documentation as an ongoing user-facing engineering practice. **Method:** practitioner guidance, checklists, cited concepts, and a continuous fictional product example. **Audience:** developers and people who work with developer documentation. The introduction presents a primer, not a graduate research synthesis. Rhetorical modes are teaching, explaining, and advocating for investment in documentation; examples supply instruction rather than controlled evaluation. (EPUB-INTRO#Par53–Par58.) **Provisional inspectional summary, retained as an intermediate output:** Docs for Developers follows a documentation project from audience research through maintenance. Its authors argue that useful documents start with what readers need to accomplish, not with the product's inventory of features. They translate those needs into content types, outlines, procedures, examples, and visuals, then use distinct editing passes to check the draft. Publishing begins a feedback cycle: teams gather reports, measure whether documents serve their purpose, improve navigation, and update or retire content as the product changes. The fictional Corg.ly service makes the sequence concrete without requiring a real customer project. The second edition also addresses AI-assisted work and machine consumption of documentation. At this inspectional stage, the strongest expected value lies in the workflow and checklists. Numerical benefits, categorical guarantees, and current AI capabilities require closer checking. The analysis below narrows several of those claims while retaining the task-centered method. **Hotspots:** chapter 1 supplies the thesis and research limits; chapter 2 defines content types; chapters 4–6 expose testable quality claims; chapter 9 contains the metrics and indexing overclaims; chapter 11 links labor and releases; appendix B carries the fastest-changing recommendations. The preface is an edition-history checkpoint. Chapters 7–8 matter for the small-team feasibility question, so they weren't skipped. **Guiding questions for the analytical pass:** Q03, Q04, Q05, Q06, Q07, Q11, Q12, Q15, Q16, Q19, Q21, and Q23. This selects 12 questions that can validate mechanisms or expose limits rather than adding a second redundant inventory. **Reading strategy chosen:** full analytical read, followed by bounded comparison with named vault notes and selected primary sources. The task requests the whole chain, and later chapters can qualify earlier claims. For reuse, revisit chapter 1 before planning, chapter 4 before review, chapter 9 before choosing metrics, and chapter 11 before a release change. ## Prompt 3 — Classification and terminology **Classification:** technical nonfiction; developer documentation and content operations; procedural and prescriptive argument, supported by practitioner cases and selected research. Intended use is planning, writing, reviewing, publishing, and maintaining docs. Adjacent traditions include user-centered design, technical communication, information architecture, docs-as-code, and developer experience. This is a system classification grounded in the introduction and chapter sequence, not a publisher-category verdict. All author definitions in this table are **paraphrases**. Competing definitions identify practical ambiguity; they aren't invented quotations from another author. | Term | Author's meaning | Competing meaning / risk | Operational definition | Example / counterexample | Evidence | | --- | --- | --- | --- | --- | --- | | User need | What people require to reach a goal. | Expressed wish; business target. | A documented task and constraint backed by observation. | Install offline / a manager wants more pageviews. | EPUB-C01#Par59; RW-440527293 | | Persona | Research-informed representative reader. | Fictional demographic stereotype. | Trace each relevant trait to research and a design decision. | Novice lacks token setup knowledge / a name and hobby with no task consequence. | EPUB-C01#Par106; RW-440527298 | | User story | A role, goal, and reason. | A feature requirement alone. | Name who needs what and why. | Developer needs error recovery / add a troubleshooting tab. | EPUB-C01#Par114 | | Journey map | Steps and experience across a goal. | Ideal happy-path flowchart only. | Include entry, failure, recovery, and outcome. | Auth failure and retry / arrows with no user state. | EPUB-C01#Par119 | | Friction log | Sequential record of expected and actual experience. | Any complaint list or formal usability study. | Fix task, environment, and version; record each mismatch. | Broken prerequisite reproduced / an unlocated dislike. | EPUB-C01#Par130; RW-440527299 | | Use case | Set of tasks addressing a user problem. | Individual feature or UI control. | State the outcome before the implementation. | Translate an audio recording / describe an upload button. | EPUB-C02#Par7; RW-440527300 | | Tutorial | Guided learning through a controlled exercise. | Any ordered instruction. | Teach a skill with a prepared route and checked result. | First supported request / production migration for an experienced user. | EPUB-C02#Par68; RW-440527303 | | How-to guide | Task directions for someone with background knowledge. | A tutorial with fewer words. | Declare assumed knowledge and the specific result. | Rotate a token / explain authentication from first principles. | EPUB-C02#Par74 | | Reference | Structured facts for lookup. | An exhaustive narrative. | Provide consistent entries, parameters, behavior, and limits. | Endpoint fields / a getting-started story. | EPUB-C02#Par91 | | Completeness | Enough information to accomplish the purpose. | Everything known about a product. | Required starting state, actions, result, and recovery are present. | A working quickstart / every configuration option inserted into it. | EPUB-C04#Par35; RW-440527338 | | Functional quality | Whether a document serves its purpose. | Spelling, visual polish, or popularity. | Observe completion, accessibility, findability, accuracy, and necessary coverage. | User completes the intended task / a polished failure. | EPUB-C09#Par20; RW-440527334 | | Structural quality | Clear, concise, consistent expression. | File layout or information architecture alone. | Review wording, order, terminology, and unnecessary text. | Stable labels / a lint score treated as user success. | EPUB-C09#Par63; RW-440527339 | | Executable sample | Code readers can run and adapt. | A sketch that merely looks runnable. | Declare dependencies, inputs, expected output, and a tested environment. | Checked request fixture / unexplained ellipsis in runnable code. | EPUB-C05#Par20; RW-440527318 | | Explanatory sample | Code illustrating a point without promising a complete program. | Broken production example. | Label omissions and the concept they serve. | A clearly marked fragment / an incomplete command presented for copying. | EPUB-C05#Par20; RW-440527317 | | Findability | Ease of reaching relevant information. | Search ranking or indexing alone. | From real entry points, locate the right task/version and next step. | Search result routes correctly / a sitemap exists but content isn't indexed. | EPUB-C09#Par45; RW-440527336 | | Document sentiment | Readers' reported feelings about docs. | Direct proof of accuracy or usability. | Interpret responses alongside task, sampling, and failure context. | Feedback after a task / one downvote treated as root cause. | EPUB-C08#Par36; RW-440527329 | | TTHW | Time to a first working result. | Complete developer experience or long-term adoption. | Fix task and starting state; record completion and failures with elapsed time. | First supported API call / only successful fast users counted. | EPUB-C09#Par42 | | Information architecture | Organization, labels, navigation, and search. | Folder tree alone. | Test routes across content and incoming links. | Prerequisite links plus task navigation / a reorganized directory without redirects. | EPUB-C10#Par11; RW-440527347 | | Docs-as-code | Engineering practices applied to documentation. | Every contributor must use Git; same date guarantees correctness. | Version, review, and test relevant content using an accessible workflow. | Reviewed doc change with behavior check / a commit as the sole quality gate. | EPUB-C11#Par27; RW-440527356 | | AI grounding | Context intended to connect AI output to product facts. | Guaranteed understanding or truth. | Identify retrieved sources, versions, permissions, and tested output behavior. | Verified source passage available to a compatible agent / unused context file. | EPUB-C09#Par50; EPUB-B#Par177 | **Contested language:** “guarantees,” “ensures,” “good,” “quality,” “AI,” “understands,” and “complete” can hide a change from mechanism to outcome. “User” can mean a paying customer, developer, operator, or prospective user; these aren't interchangeable samples. “Changelog” isn't inherently internal: the book's contrast with externally oriented release notes needs qualification for public open-source projects. (EPUB-C02#Par109.) **Category-error watchlist:** web traffic → quality; first-success speed → retention; file availability → agent consumption; source generation → runtime accuracy; nonempty alt → equivalent information; a vivid company case → a population effect; learning preferences → disability accommodations; coordinated timing → substantive synchronization. These are specific reasoning risks, not diagnoses of the authors' motives. ## Prompt 4 — Claims and dependencies Origin codes: **EA** explicit author claim; **TP** quoted or cited third-party claim. No row silently treats system inference as an author statement. The proposition column sets scope and key terms. The test column states expected evidence and a concrete weakening condition; prescriptions can be evaluated for usefulness without pretending their values are experimentally falsifiable. | ID / origin / type | Proposition and scope | Expected evidence → falsifier or limiting test | Source / questions | | --- | --- | --- | --- | | C-001 · EA · methodological | Audience research should determine developer-doc goals and scope. | Task observations change requirements → research-informed versions repeatedly serve users no better, at excessive cost. | EPUB-C01#Par25, #Par59; RW-440527296; Q03, Q17 | | C-002 · EA/TP · practical | A small 3–5-person research round can begin exposing user problems. | Formative observations across relevant users → important segments remain unseen or the sample is treated as representative. | EPUB-C01#Par80; Q05 | | C-003 · EA · methodological | A bounded friction log reveals gaps and routes some fixes to the product. | Reproduced expected/actual mismatch → reviewer expertise or an undefined starting state conceals the barrier. | EPUB-C01#Par130, #Par135; RW-440527299; Q04, Q10 | | C-004 · EA · definitional/practical | Match document type to learning, task, or lookup needs. | Reader tasks sort usefully into types → rigid separation breaks a legitimate mixed task. | EPUB-C02#Par68, #Par74, #Par91; RW-440527303; Q02 | | C-005 · EA · prescriptive | A tutorial should control its route and, in the chapter's stronger phrasing, guarantee success. | Novices finish under declared conditions → supported environments or users fail despite following the tutorial. | EPUB-C02#Par70; Q02, Q11 | | C-006 · EA · practical | Goal-focused outlines and semantic structure help drafting and reading. | Readers locate prerequisites, actions, and results → heading/outline conformity leaves task order ambiguous. | EPUB-C03#Par30, #Par41, #Par59; RW-440527308; Q10, Q18 | | C-007 · EA · methodological | Four focused passes address accuracy, completeness, structure, and clarity. | Distinct defects caught with sustainable effort → no useful added detection or excessive rework against a comparator. | EPUB-C04#Par18–Par22; RW-440527311–RW-440527314; Q06 | | C-008 · TP endorsed · prescriptive | Criticism should only be offered with a constructive suggestion. | Better review without suppressing valid reports → a person can show failure but can't supply a remedy. | EPUB-C04#Par91; RW-440527315; Q12, Q17 | | C-009 · EA · practical | Executable samples should be usable, trustworthy, and checked. | Runnable tests plus valid example data → apparent correctness fails the promised behavior or data semantics. | EPUB-C05#Par27–Par32, #Par64; RW-440527318; Q11 | | C-010 · TP cited · empirical | Fast picture detection, recall percentages, and visual-instruction studies motivate effective visuals. | Studies match the claimed population and task → recognition/recall results don't transfer to technical task completion. | EPUB-C06#Par8, #Par9, #Par17; Q07 | | C-011 · EA/TP · empirical | Research doesn't support matching instruction to claimed learning styles. | Controlled preference-by-format interaction tests → replicated useful matching effects under a specified definition. | EPUB-C06#Par29; Q20 | | C-012 · EA · practical | Visuals need equivalent accessible descriptions; body descriptions may make alt text redundant. | A reader receives all necessary meaning without seeing the image → omission or false description changes the task. | EPUB-C06#Par34, #Par48, #Par92; RW-440527322; Q19 | | C-013 · EA · practical | A release process needs ownership, checks, and a cadence scaled to the project. | A small release can be reviewed and published repeatably → process overhead blocks trivial fixes without reducing relevant risk. | EPUB-C07#Par25, #Par26, #Par43–Par49; RW-440527326; Q08 | | C-014 · EA · practical | Feedback becomes work through triage, reproduction, scope, and follow-up. | Traceable issue-to-resolution cases → channel bias or “original” rules discard recurring failures. | EPUB-C08#Par65–Par75; RW-440527332; Q17 | | C-015 · EA · evaluative | Functional quality takes priority over stylistic polish. | Compare documents against their stated purpose → a function-only definition ignores necessary access or comprehension. | EPUB-C09#Par17–Par21, #Par84; RW-440527334; Q01 | | C-016 · EA · practical | Accessible language and a roughly tenth-grade target can lower reading demands. | Audience comprehension tests → a readability score improves while comprehension or precision worsens. | EPUB-C09#Par35, #Par36; Q13 | | C-017 · EA · descriptive/practical | TTHW can indicate onboarding difficulty and correlate with ease of adoption. | Timed comparable tasks including failures → timing changes reflect setup or user mix rather than the docs. | EPUB-C09#Par42, #Par43; Q16 | | C-018 · EA · methodological | Tie metrics to a decision, baseline, organizational goal, and context. | Denominators plus qualitative explanation → raw counts reverse the conclusion once exposure or task changes are included. | EPUB-C09#Par145–Par154; RW-440527344–RW-440527346; Q16 | | C-019 · EA · causal guarantee | A comprehensive sitemap ensures indexing. | Universal indexing for valid submitted URLs → an eligible submitted URL isn't indexed. | EPUB-C09#Par50; Q21, Q24 | | C-020 · EA · causal guarantee | AGENTS.md context ensures AI tools understand retrieved docs and product relationships. | Verified consumption and correct answers across claimed tools → the file isn't loaded or an answer remains wrong. | EPUB-C09#Par50, #Par52; EPUB-B#Par177; Q21, Q24 | | C-021 · EA · methodological | Task-oriented architecture, navigation cues, and migration checks improve routes through docs. | Findability tasks and redirect tests → users or old links cannot reach supported content after restructuring. | EPUB-C10#Par48–Par53, #Par94–Par99; RW-440527353; Q18 | | C-022 · EA · predictive | Semantic URL structure helps search; opaque IDs are said to harm ranking. | Controlled indexing/ranking comparison with confounders held constant → the claimed categorical penalty isn't observed. | EPUB-C10#Par58; Q21 | | C-023 · EA · causal guarantee | Releasing code and docs together guarantees synchronization. | Coverage and behavior checks at release → both ship together but a changed behavior remains undocumented. | EPUB-C11#Par27; RW-440527356; Q15 | | C-024 · EA · prescriptive | Named ownership, impact analysis, and rewarded maintenance help sustain docs. | Maintenance work has capacity and accountability → named owners lack authority, time, or continuity. | EPUB-C11#Par20–Par24, #Par39, #Par50; RW-440527355; Q08 | | C-025 · EA · practical | Link and prose linters reduce recurring mechanical review work. | Seeded defects detected at acceptable false-positive cost → passing checks conceal task failure or maintenance costs exceed benefit. | EPUB-C11#Par56, #Par67; RW-440527358, RW-440527359; Q14 | | C-026 · EA · practical | Generated reference can track the source more accurately than manually copied facts. | Reference matches a correct specification and actual behavior → stale/incomplete source produces consistently wrong docs. | EPUB-C11#Par72, #Par73; Q11, Q14 | | C-027 · EA · practical | Retire content that no longer serves users, with migration or replacement when needed. | Supported tasks remain served and routes work → low-traffic but necessary guidance disappears. | EPUB-C11#Par83–Par94, #Par100; RW-440527360; Q22 | | C-028 · EA · prescriptive | Teams retain responsibility for AI-generated documentation quality. | Review ownership and evidence standards apply to generated work → delegation leaves unsupported output unreviewed. | EPUB-B#Par148, #Par161–Par164; Q23 | | C-029 · EA · practical | AI may assist research synthesis, drafting, examples, and feedback processing. | Total time and quality compared with a baseline → checking generated output erases savings or misses defects. | EPUB-B#Par151–Par156; EPUB-C08#Par81–Par84; Q23 | | C-030 · EA · categorical | AI cannot do user research in the human sense described by the appendix. | A clear boundary between lived experience, data collection, and synthesis → one broad prohibition conflicts with acknowledged assistance. | EPUB-B#Par138–Par140, #Par151; Q23, Q24 | | C-031 · EA · historical | ChatGPT launched in 2023. | Original dated launch record → a public launch announcement predates 2023. | EPUB-PREF#Par37; Q09, Q24 | | C-032 · EA · practical | Headings, consistent terms, versions, and context help human and machine readers. | Comprehension and retrieval tasks against tagged sources → structure is present but the relevant context isn't retrieved or used. | EPUB-C10#Par56, #Par57; EPUB-B#Par171–Par177; Q21, Q24 | ### Dependency structure Foundations are C-001 (user needs) and C-015 (purpose-based quality). C-004 and C-006 translate them into content. C-007, C-009, and C-012 connect content to checks. C-013, C-014, C-018, C-021, C-024, and C-027 form the maintenance cycle. The bridge is **system reconstruction**: observed task barriers can guide revisions only when the task, audience, and environment remain identifiable. C-010's numerical visual claims, C-019's indexing guarantee, C-020's AI guarantee, C-022's ranking claim, C-023's release guarantee, and C-031's launch date can fail without defeating goal-first writing. Failure of C-001 or C-015 would challenge the book's central project. Failure of a measurement or feedback bridge limits how confidently you can infer that a revision helps. ```mermaid flowchart TD C001["C-001 Research user needs"] --> C004["C-004 Select content for the task"] C004 --> C006["C-006 Outline and draft"] C015["C-015 Judge by purpose"] --> CHECK["C-007 C-009 C-012 Check content and access"] C006 --> CHECK CHECK --> C013["C-013 Publish with checks"] C013 --> LEARN["C-014 C-018 Gather and interpret evidence"] LEARN --> MAINT["C-021 C-024 C-027 Organize and maintain"] MAINT --> C001 EXTRA["Independent overclaims: C-019 C-020 C-023 C-031"] -.-> CHECK classDef thesis fill:#d9ead3,stroke:#38761d,color:#172517; classDef concept fill:#d9eaf7,stroke:#285f8f,color:#132b40; classDef action fill:#fce5cd,stroke:#a65d12,color:#40240a; classDef connection fill:#eadcf4,stroke:#744394,color:#2e193b; class C001,C015 thesis; class C004,C006,CHECK concept; class C013,LEARN,MAINT action; class EXTRA connection; ``` The dashed edge means “test separately,” not logical support. Dependencies express the reconstructed workflow, not a proven causal model. ## Prompt 5 — Quantitative reasoning policy **Policy:** use numerical probabilities only when the task has defined events and relevant data. This book offers no common dataset that supports posterior probabilities for its workflow. The update table therefore uses qualitative likelihood impact. Confidence concerns a **scoped proposition**, not the prestige of its author or the number of citations. | Band | Operational meaning | | --- | --- | | Low | Evidence is absent, indirect, or contradicted for the stated scope. | | Uncertain | Competing explanations or missing tests prevent a direction. | | Moderate | A mechanism and relevant examples support use with conditions. | | High | Direct verification or converging relevant evidence supports the narrow claim. | | Not empirical | A definition or responsibility principle needs explicit values and useful application, not an invented probability. | Confidence ranges below span adjacent verbal bands when population or implementation remains uncertain. They aren't hidden percentage estimates. Use “strongly/moderately increases,” “no meaningful update,” or “moderately/strongly decreases.” An increase for a narrowed repair must not be recorded as an increase for the original absolute claim. **Calibration warnings:** one book citing one study ten times remains one study; multiple company examples may share professional assumptions; successful users and vocal customers are selected samples; failures and abandoned sessions belong in denominators. A prose score, pageview, or short completion time is a proxy until connected to the target outcome. Before/after comparisons can reflect product changes and recruitment. The 13-millisecond and 28% numbers have specific tasks and assumptions. A study's statistical significance isn't an effect size, and an effect size in one task isn't a practical benefit in another. No p-values are calculated here. The completed priors/posteriors table appears under Prompt 7, after evidence evaluation. There is no numerical update before examining the evidence. ## Prompt 6 — Chapter analysis and evidence ledger These are filled analytical slots. **Reader response is unknown for every chapter in this edition**; the older highlight IDs identify prior attention only. Each “We infer” sentence records the system's response. Corg.ly examples are instructional fiction unless another source is named. ### Chapter 1 — Understanding Your Audience **Purpose/thesis:** replace assumptions about readers with evidence about goals, experience, and context. **Claims/terms:** C-001–C-003; curse of knowledge, persona, user story, journey map, friction log. **Evidence/examples:** practitioner reasoning, cited knowledge-bias research, Corg.ly personas, and a sequential log of expected and actual behavior. Research can begin with support material and colleagues but should reach users; the chapter explicitly discusses limited time and diverse recruitment. (EPUB-C01#Par60, #Par72, #Par82, #Par130.) **Counterexample/assumption:** a developer following a familiar path can miss an onboarding obstacle. Three to five participants can expose a problem without representing all users. A persona's demographic detail is useful only if grounded and task-relevant. The Ichiro example's lifestyle details deserve scrutiny rather than automatic reuse. **Unanswered:** how should recruitment cover users who never reached support or abandoned installation? **Spine/response:** research supplies the scope for every later check. We infer that the friction log's strongest feature is routing: some barriers require a product change, not more prose. “Fix software” still needs feasibility and impact assessment. **Older attention:** RW-440527296, RW-440527298, RW-440527299. ### Chapter 2 — Planning Your Documentation **Purpose/thesis:** choose content around what a reader needs to learn, do, or look up. **Claims/terms:** C-004, C-005; use case, README, quickstart, concept, tutorial, how-to, reference, glossary. **Evidence/examples:** content-type descriptions and a plan connecting audience, takeaway, prerequisites, features, and use cases. The tutorial/how-to distinction aligns with a reader's starting knowledge. (EPUB-C02#Par68–Par80, #Par130–Par136.) **Counterexample/assumption:** ten steps aren't an empirical complexity boundary; a short procedure can require more background than a long one. Links at the bottom reduce distraction only when prerequisites and essential definitions remain available at the point of need. A public open-source changelog can serve external readers, so the internal/external distinction with release notes isn't categorical. **Unanswered:** what minimum content mix serves a small project without fragmented pages? **Spine/response:** the plan turns research into a reviewable content contract. We infer that a task's starting state and expected result matter more than making every page fit a genre label. **Older attention:** RW-440527300, RW-440527302, RW-440527303, RW-440527306. ### Chapter 3 — Drafting Documentation **Purpose/thesis:** establish a goal and outline, then write a draft that can be improved. **Claims/terms:** C-006; semantic headings, procedure, callout, warning, caution, note. **Evidence/examples:** successive Corg.ly outlines, uploads, ordered actions, and callouts placed before relevant actions. Alternative drafting methods include talking, paper, and writing sections out of order. AI-generated drafts still require product knowledge and review. (EPUB-C03#Par41, #Par57, #Par59, #Par67, #Par86–Par91, #Par125.) **Counterexample/assumption:** the “at most 28%” reading claim shouldn't become a universal reader limit or be extended to screen-reader behavior. Nielsen's underlying calculation estimates average web-page reading under particular timing assumptions; it isn't a rule for every visit or reader. [Nielsen's calculation](https://www.nngroup.com/articles/how-little-do-users-read/). **Unanswered:** which of this audience's tasks require scanning, sustained reading, or both? **Spine/response:** drafting makes task structure visible before polishing. We infer that the chapter's paragraph and list-length thresholds are editing prompts, not validity tests. **Older attention:** RW-440527308 and RW-440527309; only two records exist for this provisional chapter group. ### Chapter 4 — Editing Documentation **Purpose/thesis:** review for technical accuracy, completeness, structure, and clear concise expression, with explicit review roles. **Claims/terms:** C-007, C-008; focused pass, subject-matter review, new-reader review, constructive feedback. **Evidence/examples:** separate questions test whether instructions work, prerequisites exist, headings make sense, and language avoids unnecessary assumptions. Search arrivals need enough local context. (EPUB-C04#Par25, #Par34, #Par44, #Par73.) **Counterexample/assumption:** the four-pass order may need iteration when an accuracy correction changes structure. The quoted rule requiring a constructive suggestion with every criticism can exclude someone who identifies a failure but cannot design its fix. Chapter 8's issue template makes a possible solution optional, supplying an internal correction. **Unanswered:** how much review is enough for different change risks? **Spine/response:** editing connects draft quality to the promised user result. We infer that the four questions transfer better than a rigid four-stage approval process. **Older attention:** RW-440527311–RW-440527316. ### Chapter 5 — Integrating Code Samples **Purpose/thesis:** distinguish illustrative fragments from code readers can run, and make both understandable. **Claims/terms:** C-009, C-026; explained, concise, clear, usable, trustworthy, executable, explanatory. **Evidence/examples:** requests and JSON responses, prerequisites, expected output, placeholders, error behavior, testing, and versioned source. Every additional language adds upkeep. (EPUB-C05#Par20, #Par34, #Par38, #Par64, #Par68.) **Counterexample/test:** Listings 5-2 and 5-3 contain `2021-02-29T17:56:28.000Z`. Parsing that timestamp raises a day-out-of-range error because 2021 isn't a leap year; the February 22 control parses. This is an example-data defect even though the JSON string is syntactically legal. (EPUB-C05#PC2, EPUB-C05#PC3.) The fictional API wasn't executed, and this test doesn't establish defects in every listing. **Spine/response:** samples expose the difference between readable output and valid behavior/data. We infer that executable assertions should accompany published example fixtures where the contract makes them testable. **Older attention:** RW-440527317–RW-440527319. **Unanswered:** which sample properties belong in routine validation versus human explanation review? ### Chapter 6 — Adding Visual Content **Purpose/thesis:** visuals should convey necessary information with less reader effort and remain accessible and maintainable. **Claims/terms:** C-010–C-012; screenshot, process diagram, swimlane, alt text, caption, transcript. **Evidence/examples:** annotated screens, diagrams, visual design conventions, and research citations of unequal relevance. The chapter recognizes bandwidth, devices, captioning, source-file maintenance, and non-color cues. (EPUB-C06#Par34, #Par37, #Par73, #Par95, #Par101.) **Counterexample/assumption:** target detection at 13 ms isn't evidence that a developer understands an architecture diagram in 13 ms. A body description justifies empty alt only when the required equivalent information is present; “blank” alone isn't an accessibility solution. A text description can also be wrong, as the EPUB's figures demonstrate. **Unanswered:** does a given visual improve completion or recovery for this task and audience? **Spine/response:** media must pass the same purpose test as prose. We infer that diagrams need both a semantic review and an accessible equivalent; visual inspection alone misses the alt-text channel. **Older attention:** RW-440527320–RW-440527323. ### Chapter 7 — Publishing Documentation **Purpose/thesis:** establish a release path with a clear owner, approver, timing, and checks. **Claims/terms:** C-013; content release process, cadence, approval, rendered content. **Evidence/examples:** a process can be a checklist; a small fix can receive one peer review. Try publishing a small document before investing in automation. Review includes instructions, prerequisites, links, rendering, and placement. (EPUB-C07#Par25, #Par26, #Par43, #Par48, #Par49.) **Counterexample/assumption:** a large release calendar doesn't fit every continuously deployed project. A typo and a migration guide don't need identical review cost. The book's small-team provisions rebut the older review's blanket “large organization” limitation. **Unanswered:** what checks are mandatory when an error would block or harm a user? **Spine/response:** a checked draft becomes available through a verified publication path. We infer that rendered content and reachable navigation must be checked after publication as well as in a working file. **Older attention:** RW-440527324–RW-440527327. ### Chapter 8 — Gathering and Integrating Feedback **Purpose/thesis:** choose manageable feedback channels, triage reports, and close the loop. **Claims/terms:** C-014, C-029; sentiment, survey, user council, original/reproducible/scoped issue, priority. **Evidence/examples:** small projects can start with an email address or issue tracker; optional suggested solutions; dedicated triage separates docs problems from product problems. The AI discussion requires oversight and cautions against automatic responses that miss context. (EPUB-C08#Par27, #Par65–Par75, #Par81–Par88.) **Counterexample/assumption:** a negative troubleshooting-page rating can reflect the underlying product failure. Duplicate reports shouldn't create duplicate fixes, but their frequency remains useful evidence. A council of key customers doesn't represent people who never became customers. **Unanswered:** how will quiet, excluded, or unsuccessful users enter the evidence stream? **Spine/response:** publication produces learning only when a report is interpreted and routed. We infer that requesting environment and observed failure is justified; requiring a solution isn't. **Older attention:** RW-440527328, RW-440527329, RW-440527331, RW-440527332. ### Chapter 9 — Measuring Documentation Quality **Purpose/thesis:** define quality by purpose, then choose measurements that can inform a decision. **Claims/terms:** C-015–C-020; functional/structural quality, three Cs, findability, TTHW, baseline, organizational goal. **Evidence/examples:** the chapter distinguishes successful function from polished expression and explains that rising user numbers can raise support counts even while support per user falls. It also gives simplistic positive interpretations of some traffic changes. (EPUB-C09#Par84, #Par145–Par154.) **Counterexample/verification:** more quickstart visits can mean interest or repeated failed attempts. A sitemap doesn't guarantee indexing, and a context file doesn't guarantee agent understanding. The source itself acknowledges that not every agent uses AGENTS.md. (EPUB-C09#Par50, #Par52.) Its tenth-grade target is a heuristic; formulas don't measure comprehension. **Spine/response:** measurement is the bridge from change to justified belief about usefulness. We infer that cohort, denominator, task, and failure count belong beside timing and sentiment. **Older attention:** RW-440527333–RW-440527346, the densest saved group. **Unanswered:** which changes affect user success independently of product improvements or recruitment? ### Chapter 10 — Organizing Documentation **Purpose/thesis:** organize content so readers can find their current task and recover from arriving in the wrong place. **Claims/terms:** C-021, C-022, C-032; sequential/hierarchical/web structures, landing page, navigation cue, inventory, card sort, redirect. **Evidence/examples:** task groupings, headings, prerequisites, breadcrumbs, keep/remove/merge/split decisions, and migration checks. Machine-oriented guidance includes explicit versions and stable concepts. (EPUB-C10#Par48–Par57, #Par63–Par72, #Par94–Par100.) **Counterexample/verification:** a well-organized folder tree can still strand an external search visitor. Keyword-bearing URLs don't establish a universal ranking effect. Figure 10-1 depicts eight connected squares but describes molecular bands in alt text; the representation fails its own communication goal. (EPUB-C10#Fig1.) **Spine/response:** architecture maintains relationships, not just page order. We infer that redirects and task-entry tests belong in the same change as a reorganization. **Older attention:** RW-440527347–RW-440527354. **Unanswered:** which paths should remain stable for supported versions and external references? ### Chapter 11 — Maintaining Documentation **Purpose/thesis:** assess user impact, budget maintenance, assign responsibility, and automate recurring checks before retiring content. **Claims/terms:** C-023–C-027; versioning, ownership, toil, generated reference, deprecation. **Evidence/examples:** impact questions, a historical Kubernetes release case, Google maintenance practice, source generation, link checking, and an example that replaces a burdensome tutorial with a shorter maintainable guide. Maintenance can be recognized in performance expectations. (EPUB-C11#Par20–Par27, #Par50, #Par56, #Par92–Par94.) **Counterexample/assumption:** simultaneous publication leaves undocumented behavior possible. “Last edited” isn't “last verified.” A named owner without time or authority can't maintain a large collection. Low traffic alone doesn't justify deleting an essential recovery page. Current Kubernetes processes weren't checked; the book's account remains a historical example. **Spine/response:** maintenance returns the lifecycle to changing user needs. We infer that review triggers should track supported behavior and task changes, not just a calendar or last-edit field. **Older attention:** RW-440527355–RW-440527361 and RW-760358744. **Unanswered:** who funds maintenance when its benefits accrue across teams? ### Front matter and appendices **Foreword/introduction/preface:** practitioner narratives explain why developers should write and why the second edition adds AI. They don't measure a general effect on adoption or writer productivity. The preface's ChatGPT launch year is wrong; this doesn't erase its description of AI's influence on documentation work. C-031; EPUB-PREF#Par37. No personal response from Courtney is available. **Appendix A:** specialist help can address research, complex launches, architecture, localization, versioning, or AI-related work. Its purpose is a staffing decision, not a requirement that every project hire a writer. The assumption is that needed expertise or capacity may lie outside the current team; the unanswered question is when consultation suffices. We infer that a defined deliverable and bottleneck should precede a hiring recommendation. Evidence is practitioner guidance, not a comparative hiring study. No older highlight was matched to this appendix. **Appendix B:** C-028–C-030 and C-032 make AI assistance subject to editorial responsibility. Terms include LLM, RAG, agent, grounding, and prompt library. The text allows research-data synthesis while making broader statements about what AI cannot do; separate those tasks from human experience and actual participant observation. Simulated novice responses can't establish real novice success. Prompt reuse may reduce setup work, but it doesn't verify answers. We infer that total review cost and observed error rate decide whether assistance helps. Still uncertain: current product capabilities, environmental costs by workflow, and whether any particular context file is consumed. No second-edition AI highlight set was verified. **Appendix C and bibliography:** courses, Write the Docs, Diátaxis, The Good Docs Project, and related books provide a lineage and routes to further study. The resources include Falconer; the author biography discloses David Nunez's connection to that company. That is a relevant disclosed interest, not evidence of improper selection. We infer that resource choice still requires current fit and cost checks. The 52-entry bibliography identifies sources; this session doesn't turn that list into 52 verified studies. Older attention: RW-440527362–RW-440527364. ### Argument spine and completed reading plan 1. **Starting assumption:** other people lack some of the knowledge the developer has. 2. **Definition:** a document serves a user purpose; completeness depends on that purpose. 3. **Premises:** research exposes tasks and constraints; content structure can make required information available. 4. **Intermediate conclusion:** review should test accuracy, necessary context, structure, language, examples, and access. 5. **Central conclusion:** documentation is a maintained product capability, with publication, feedback, and ownership. 6. **Practical recommendation:** run a bounded user task, repair barriers, publish through checks, and revise with interpretable evidence. **Gaps:** research isn't automatically representative; editorial checks aren't user trials; metrics don't identify causes by themselves; coordination doesn't guarantee accuracy. This reconstruction is faithful to the workflow without importing the book's absolute guarantees. The pass followed spine order, with high attention on chapters 1, 4–6, 9, 11, and appendix B. The index served navigation rather than interpretive evidence. Synthesis checkpoints were research → plan, draft → review, publish → measure, and maintain → retire. External checks focused on concrete date, indexing, agent-file, and visual-evidence claims. Completion criteria before evaluation were met: all chapter slots filled, origins and locators assigned, 32 claims bounded, counterexamples recorded, and missing evidence marked. ### Evidence ledger | Evidence | Claims | Type and source | Independence / quality / limits | Related highlights | | --- | --- | --- | --- | --- | | E01 | C-001–C-007 | EPUB chapters 1–4: method and fictional worked example. | One practitioner synthesis; useful operational detail, no controlled comparison. | RW-440527299, RW-440527303, RW-440527311 | | E02 | C-008 | Quoted plussing rule in EPUB-C04#Par91; optional solution in chapter 8 template. | Internal textual contrast; direct for wording, not empirical team outcomes. | RW-440527315 | | E03 | C-009 | Native Listings 5-2/5-3 and timestamp parsing with valid control. | Direct local test; establishes one repeated data defect, not fictional API behavior. | RW-440527318 | | E04 | C-010 | Potter et al. 2014 institutional abstract: target detection at 13 ms. | Primary author/institution abstract; relevant to detection, indirect for documentation comprehension. | No exact corresponding highlight. | | E05 | C-011 | Chapter 6 learning-style discussion and cited research trail. | Book claim checked for wording; full cited paper not independently read. | No exact corresponding highlight. | | E06 | C-012 | 22 numbered figures visually inspected against EPUB text; W3C image decision tree. | Direct artifact evidence plus independent normative guidance; no screen-reader session. | RW-440527322 | | E07 | C-013–C-018 | EPUB chapters 7–9: checklists, feedback examples, metrics caveats. | One source, not seven independent experiments; actionable but outcome effects unmeasured. | RW-440527326, RW-440527332, RW-440527344 | | E08 | C-019 | Google Search Central sitemap overview. | Primary authority for its crawler/indexing service; explicitly rejects guarantee. | None; new-edition passage. | | E09 | C-020, C-032 | AGENTS.md official format documentation and EPUB caveat. | Primary format scope; doesn't prove any given runtime loaded a file. | None; new-edition passages. | | E10 | C-021, C-022 | EPUB architecture procedure; Google URL guidance. | Usability rationale plus search-provider recommendation; no isolated ranking experiment. | RW-440527353 | | E11 | C-023–C-027 | EPUB chapter 11 and historical company cases. | Shared practitioner source; directly supports proposed procedure, not universal effect. | RW-440527355, RW-440527356, RW-440527360 | | E12 | C-028–C-030 | Appendix B and chapter 8 AI caveats. | Guidance and internal distinctions; no measured total-cost comparison. | None matched for new AI material. | | E13 | C-031 | Original OpenAI launch announcement, November 30, 2022. | Direct dated primary record; strong for launch date only. | None. | | E14 | C-004 | Diátaxis framework and the book's resource list. | Independent framework definition; conceptual agreement isn't outcome evidence. | RW-440527303 | | E15 | C-006, C-010, C-016 | Nielsen's 2008 calculation of average page reading. | Primary analysis of a particular study; task and averaging assumptions limit transfer. | None matched for the numerical claim. | ## Prompt 7 — Evaluation and fair criticism ### Strongest reconstruction **Author says:** understand readers, write toward a task, check the content, publish it, and maintain it as the product changes. **Author implies:** documentation failures are often failures of missing context, workflow, or ownership rather than grammar alone. **We infer:** the practices help when a team can connect each change to a defined user task and verify the result. **Still uncertain:** the size of that benefit in your environment and the minimum process that sustains it. Grades assess support for the stated claim, not the author's competence: **A** direct strong relevant support; **B** substantial but bounded; **C** plausible/incomplete; **D** indirect or poorly matched; **F** contradicted or materially overstated; **N/A** primarily definitional or normative. A method can merit a trial with grade C; a field guide needn't be a randomized trial to be useful. A failed absolute can have a useful narrower repair. ### Claim-by-claim evaluation The inventory supplies each author's claim and source. This table evaluates every inventory row; its objections and repairs are system analysis. | Claim | Support and grade | Strongest objection / counterexample | Current conclusion and repair | | --- | --- | --- | --- | | C-001 | E01 gives concrete research-to-task procedures. **B** for bounded practice. | Staff proxies miss people who abandon or can't access the product. | Use direct task evidence and describe recruitment gaps. Don't equate available customers with all users. | | C-002 | Small formative rounds can expose barriers; sample advice is purpose-dependent. **C**. | One segment's five users can miss another segment's blocker. | Repeat small rounds across relevant conditions; don't make prevalence or completeness claims from the count. | | C-003 | The log specifies expected/actual observations and routing. **B**. | A knowledgeable evaluator supplies missing steps unconsciously. | Record starting state and environment; add a less-familiar user before generalizing. | | C-004 | Coherent content-type definitions and examples; E14 comparison. **N/A** for taxonomy. | One page may need explanation plus task steps. | Use reader need to choose the dominant form; allow necessary mixed content. | | C-005 | Controlled tutorial design is actionable, but success guarantee is unsupported. **F** for the guarantee. | A followed tutorial fails on a supported but untested environment. | Promise a tested route under declared prerequisites; include verification and recovery. | | C-006 | Draft outlines and semantic headings expose task order. **B**. | A structurally tidy page can omit a prerequisite or use unfamiliar labels. | Test navigation and completion; treat sentence/list thresholds as heuristics. | | C-007 | Four passes separate distinct questions with examples. **C** for comparative benefit. | A small correction doesn't need four separate meetings; ordering can cause rework. | Keep all four questions, scale execution and repeat passes when needed. | | C-008 | E02 verifies the endorsed quotation, not a universal team benefit. **N/A** for the norm; reject its mandatory form. | A novice or disabled user can demonstrate failure without knowing a fix. | Require respect and useful observations, not a remedy from every reporter. Chapter 8 supports this repair. | | C-009 | E03 directly illustrates why semantic checks matter; testing rationale is clear. **B** for practice. | Syntactically valid JSON carries an impossible timestamp. | Check example data as well as syntax and explained behavior. The book's own defect strengthens this need without proving all examples are broken. | | C-010 | Cited visual statistics concern different tasks; E04 is recognition research. **D** for broad transfer. | Detecting a named picture isn't understanding a process or completing an API task. | Keep the task-specific visual hypothesis; drop universal retention/productivity percentages from recommendations. | | C-011 | A relevant research citation is supplied; full paper wasn't independently examined. **C** in this session. | Rejection of preference matching can be misused to deny captions or text alternatives. | Keep empirical matching claims scoped; accessibility requirements remain separate. | | C-012 | W3C guidance and direct figure inspection establish need for equivalent information. **B**, conditional. | Nonempty alt describes an unrelated scene; blank alt can hide necessary meaning. | Review semantic equivalence, not mere presence. Empty alt requires an appropriate decorative/redundant role. | | C-013 | Concrete scaled release examples; explicit small-fix path. **B**. | Requiring a committee for a typo consumes capacity without a relevant benefit. | Use a risk-appropriate checklist and confirm published content can be reached. | | C-014 | Triage procedure and optional solution template are usable. **B**. | “Original” can be misread as discarding repeated reports. | Merge duplicate work while preserving recurrence evidence; route product issues instead of dismissing them. | | C-015 | A coherent purpose-based quality standard. **N/A**. | A narrow organizational goal may conflict with a user's successful cancellation or exit. | State the user's goal explicitly; include access and informed choice in success. | | C-016 | Plain-language rationale is plausible; grade threshold isn't validated for each audience. **C**. | Shortening names or deleting definitions improves a formula but harms understanding. | Use a score as an editorial signal; test comprehension and retain necessary precision. | | C-017 | The book identifies the proxy and its limits. **C** for relation to adoption. | Fast first success may coexist with poor reliability or no return use. | Report starting state, completion, failures, and later outcomes separately. | | C-018 | Explicit baseline/decision questions and denominator caveat. **B** for method. | Traffic tables can still suggest improvement without causal identification. | Use rates and qualitative context; call uncontrolled changes associations. | | C-019 | E08 explicitly contradicts indexing assurance. **F**. | Submission doesn't oblige Google's systems to crawl or index a URL. | A sitemap helps discovery; verify indexing separately. [Google's sitemap overview](https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview). | | C-020 | E09 supports a context convention, not guaranteed understanding. **F** for the guarantee. | A runtime ignores the file or retrieves it but gives a wrong answer. | Verify consumption and behavior in the intended agent. [AGENTS.md format](https://agents.md/). | | C-021 | Inventory, navigation, and migration procedure covers real failure routes. **B**. | A new tree breaks old deep links or buries urgent recovery content. | Include task-entry and redirect checks; keep rationale for future changes. | | C-022 | Google recommends logical, readable URLs; no universal penalty is established. **D** for categorical ranking claim. | A necessary stable identifier can coexist with discoverable, useful content. | Prefer understandable stable URLs; don't promise a ranking effect. [Google URL guidance](https://developers.google.com/search/docs/crawling-indexing/url-structure). | | C-023 | Timing coordination removes one source of mismatch, not all. **F** for the guarantee. | Code and docs ship together with an omitted behavior change. | Pair release coordination with impact coverage and behavior checks. | | C-024 | Ownership and maintenance incentives have an explicit mechanism; effect size absent. **C**. | An owner has responsibility but no time, authority, or backup. | Budget capacity and recognize maintenance work; identify a durable responsible role. | | C-025 | Tool mechanisms are concrete and bounded; no local linter benchmark run. **B** for mechanical checks. | Passing lint says nothing about an undocumented prerequisite. | Automate known mechanical checks and preserve functional/user review. | | C-026 | Generation can remove manual copying drift. **C**. | A stale specification generates consistent but false reference content. | Test source correctness and product behavior separately from generation. | | C-027 | The chapter includes migration and replacement, not deletion alone. **B**. | A rare recovery procedure has low views but remains necessary. | Evaluate supported tasks, unique information, and replacement routes before retiring. | | C-028 | Clear editorial-responsibility principle. **N/A**. | “Human reviewed” can name a ritual without specifying what was checked. | Assign an accountable reviewer and explicit evidence checks. | | C-029 | Plausible use cases and warnings, without net-effort measurements. **C**. | A fluent draft costs more to verify than a source-grounded manual draft. | Run a bounded total-effort and error comparison before adopting a workflow. | | C-030 | Human experience differs from model output, but “research” covers multiple activities. **D** for blanket capability wording. | The same appendix allows AI to synthesize research data. | Separate collection, synthesis, simulation, and participant evidence. Don't treat simulated users as observed users. | | C-031 | E13 dates the original public launch to November 30, 2022. **F**. | The launch announcement precedes the preface's year. | Correct the year to 2022. [Original announcement](https://openai.com/index/chatgpt/). | | C-032 | Semantic structure and versions have a plausible retrieval mechanism. **C** for improved AI outcomes. | Clean structure doesn't ensure retrieval, permissions, relevance, or faithful generation. | Test human comprehension and machine retrieval separately. Keep source/version metadata without claiming universal success. | ### Direct checks and scope of their results **Example-data reproduction:** Python's ISO timestamp parser rejects `2021-02-29T17:56:28.000Z` after converting the UTC suffix to `+00:00`; the February 22 example passes. This tests calendar validity. It doesn't test API availability, authentication, or the completeness of a sample program. **Image equivalence:** Figure 10-1's native alt text begins “Eight vertical lanes show dark bands near the middle,” then describes similar-sized molecules. The image is eight black squares connected in a horizontal sequence, captioned “Sequential structure.” Figure 3-4's alt text introduces a Corgi-only restriction while the pictured caution concerns permission to record dogs. Figure 3-3 misnames Corg.ly as “Corel Y.” These are observed content mismatches, not an inference about how the descriptions were produced. (EPUB-C10#Fig1; EPUB-C03#Fig3; EPUB-C03#Fig4.) **Visual research:** the institutional abstract of Potter, Wyble, Hagmann, and McCourt's 2014 paper reports detection of named target pictures in rapid sequences, including 13-ms presentation. That supports a narrow detection result; it doesn't validate diagram comprehension, long-term retention, or documentation outcomes. The full study data weren't reanalyzed. [Institutional research record](https://pure.psu.edu/en/publications/detecting-meaning-in-rsvp-at-13-ms-per-picture/). ### Priors, evidence impact, and revised positions | Claim | System starting position | Evidence / dependence | Likelihood impact | Revised position / confidence range | | --- | --- | --- | --- | --- | | C-001 | Research can reveal missing context; moderate. | E01 supplies mechanism and examples from one book. | Moderately increases confidence in a bounded procedure. | Moderate–high that relevant research can expose gaps; local benefit unmeasured. | | C-003 | Bounded logs reveal barriers; moderate. | E01 records expected/actual and product routing; no user experiment here. | Moderately increases confidence in operational usefulness. | Moderate; supplement expert self-testing with unfamiliar users. | | C-007 | Four passes improve defect detection; moderate. | Same-source checklists, no comparative review trial. | No meaningful update in comparative effect. | Moderate; retain as a candidate workflow. | | C-009 | Runnable examples require tests; high. | E03 independently reproduces a semantic fixture failure. | Moderately increases confidence in including data checks. | High for the need to check promised properties; no blanket sample verdict. | | C-010 | Relevant visuals can help; moderate. | E04 supports a narrower perceptual task; cited effects aren't interchangeable. | Strongly decreases confidence in broad numerical transfer. | Low for universal percentages; moderate for testing task-relevant visuals. | | C-017 | TTHW is incomplete; moderate. | E07 explains scope but supplies no isolated adoption estimate. | No meaningful update about causal adoption effects. | Moderate for diagnosis; uncertain for predicting retention. | | C-018 | Counts need context; high. | E07 includes explicit per-user denominator reasoning. | Moderately increases confidence in the proposed interpretation discipline. | High for denominator requirement; uncertain about any unsampled site. | | C-020 | Context file may help compatible agents; uncertain. | E09 defines a convention; no runtime consumed-file test here. | Strongly decreases confidence in the guarantee. | Low for universal assurance; uncertain for a specific untested deployment. | | C-023 | Coordination reduces mismatch risk; moderate. | E11 provides a process, not coverage proof. | No meaningful update for the narrow timing mechanism; decreases for guarantee. | Moderate for risk reduction; low for synchronization without behavior checks. | | C-029 | AI assistance might save effort; uncertain. | E12 provides proposals and review cautions, no net-cost experiment. | No meaningful update. | Uncertain until comparable source/quality/time checks run. | ### Bias and reasoning audit - **Generalization beyond a study task — material for C-010:** recognition and recall numbers motivate a broader documentation claim without matching the outcome. Repair by measuring the actual task; this leaves the visual-design advice intact. - **Guarantee language — material for C-005, C-019, C-020, C-023:** a helpful input becomes a promised result. Indexing is directly contradicted by the responsible provider; the other assurances omit necessary conditions. Replace guarantees with tested scopes and verification. - **Selection effects — moderate for C-001, C-002, C-014:** support users and councils are accessible but incomplete samples. The book's explicit diversity and direct-user advice partly repairs this risk. - **Proxy confusion — moderate for C-017, C-018:** traffic and timing have multiple causes. The book also cautions about context and denominators, so it would be unfair to describe the entire chapter as naive metrics advocacy. - **Terminology shifts — moderate for C-030:** “user research” shifts between human understanding and assistance with research material. Separate activities before evaluating capability. - **Criticism gate — material access risk for C-008:** a solution requirement can silence accurate problem reports. This is a procedural weakness, not evidence of the authors' intentions. The presence of source errors doesn't establish that the book was AI-generated, that its authors are careless in general, or that its central method fails. None of those conclusions follows from the tests performed. ### Corrections to the prior review 1. **Small-team applicability:** replace the blanket claim that the book assumes a large organization with a narrower observation: some examples involve large teams, but chapters 1, 7, and 8 explicitly offer limited-research, checklist, and single-channel options. 2. **Constructive criticism:** preserve the old quotation as source history, but don't adopt its mandatory-solution rule. A report can be actionable without a proposed remedy. 3. **Docs and code released together:** retain coordination as a practice; remove any implication that timing proves substantive consistency. 4. **Reader voice:** the earlier personal reflections remain archived, not newly attributed to Courtney. This session's recommendations are labeled system analysis. ## Prompt 8 — Systems, context, and intellectual lineage ### Context available to the authors The 2021 first edition and 2026 revision span a change from established developer-documentation workflows to explicit discussion of AI-assisted writing and machine retrieval. The preface describes the pandemic-era first edition and adds AI as a reason for revision. The chapter sequence remains a lifecycle: audience, content, release, feedback, and upkeep. This interpretation comes from this edition and the earlier highlights; a full textual diff against the first edition wasn't performed. Institutionally, the book draws on practitioners working around developer platforms, documentation teams, support, and engineering. Kubernetes and Google examples make responsibilities visible, but organizational scale, authority, and available labor differ. The book also provides small-project paths. Economics enters through support cost, adoption, review effort, and maintenance capacity. These are organizational incentives, not direct measures of a user's welfare. A successful export or account closure may help a user while failing an adoption target. (EPUB-C09#Par95; C-015, C-018, C-024.) The record is shaped by English-language technical communication and software-industry practice. Named authors and cited professionals have agency in that record; Corg.ly personas are constructed teaching devices. They aren't interviews with disabled developers, translators, maintainers of underfunded projects, or people unable to access the product. Their absence as first-person evidence limits what the examples establish, even when the advice explicitly encourages inclusive research. ### Lineage and competing interpretations | Tradition or comparison | Connection | Difference / boundary | | --- | --- | --- | | User-centered design and technical communication | Chapter 1 begins with goals and context; chapters 4 and 9 test usefulness. | Personas and self-run logs don't replace representative research. | | Diátaxis | Learning, doing, reference, and explanation distinguish reader needs. The book lists it as a resource. | A classification is a design aid, not proof every page must contain one isolated type. [Diátaxis](https://diataxis.fr/). | | Information architecture | Navigation, labels, inventories, and routes receive a dedicated chapter. | Filesystem organization alone doesn't establish findability. | | Docs-as-code and SRE maintenance | Versioning, review, testing, toil, and ownership connect writing to engineering. | Publishing a commit isn't equivalent to verifying user-facing behavior. | | [[4. Archives/Book reviews/Letting Go of the Words|Letting Go of the Words]] | The existing vault review also emphasizes audience, task, and content governance. | Comparison is with that note; the source book wasn't reread here. | | [[4. Archives/Book reviews/The Product is Docs|The Product is Docs]] | The existing review gives more organizational framing for treating documentation as a product. | Don't count agreement between two vault summaries as independent empirical validation. | | [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure|Documentation Is Dual-Audience Infrastructure]] | Human and machine consumption motivates explicit structure and context. | Delivery format, retrieval, and answer correctness require separate checks. | | [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review|Friction Logging Is the DevRel Equivalent of Code Review]] | Both emphasize structured inspection of developer experience. | This reading supports a useful practice, not an “only practice” or universal ranking claim. | **Competing interpretations:** the workflow can be read as a quality system for users, as an organizational adoption/support strategy, or as a writing craft guide. The text contains all three. Conflicts become visible when organizational metrics diverge from user goals or when process overhead displaces writing and research. A faithful application states which goal governs the decision. ### Context added in this session The dated launch announcement corrects an event that predates publication; it isn't a later development. Current primary sitemap and AGENTS.md guidance narrows claims about infrastructure and agents. No claim is made that later products have resolved the appendix's capability limits. New AI capability, pricing, and retrieval behavior remain drift questions. Inferring how erroneous alt text was produced would be speculation; this note doesn't do that. ## Prompt 9 — Inclusion and accessibility audit ### Inclusion strengths **Textual evidence:** chapter 1 names diversity in age, gender, disability, ethnicity, and class as recruitment considerations; it asks about constraints and context, not just developer seniority. Chapter 3 offers more than one drafting method. Chapters 4 and 9 address bias, idiom, clear language, and necessary context. Chapter 6 discusses contrast, non-color cues, bandwidth, captions, transcripts, and image descriptions. Chapter 11 treats maintenance as work that should receive recognition. (EPUB-C01#Par82; EPUB-C03#Par125; EPUB-C04#Par49–Par53; EPUB-C06#Par34, #Par37, #Par73, #Par101; EPUB-C11#Par50.) These passages establish inclusive intentions and concrete practices. They don't establish that every example or the supplied EPUB provides equivalent access. ### Omission and exclusion risks | Dimension | Textual evidence / system inference | Consequence and adaptation | | --- | --- | --- | | Agency | Authors and teams define tasks; users often appear through research artifacts or fictional personas. | Invite users to explain goals and challenge the problem definition, not just validate a draft. | | Race, ethnicity, gender | Recruitment diversity is explicit; persona demographic details can become shorthand. | Trace traits to relevant research; don't treat a demographic label as a skill, preference, or behavior. | | Class and money | Sandboxes, video, analytics, and specialist help cost effort or money; the text sometimes notes this burden. | Provide local/text-first paths and scale process to available capacity. | | Geography and language | English examples and Western left-to-right diagram conventions appear; chapter 6 qualifies the latter. | Test translated labels, reading direction, local conventions, and non-English search paths. | | Disability | The text advocates alternatives, but native alt text sometimes conveys false information. | Have the same technical review cover image meaning and its equivalent text. | | Neurodiversity | Alternative drafting modes, structure, and reduced irrelevant detail can help; direct outcome evidence is limited. | Offer explicit goals, predictable navigation, and flexible pacing without assigning a universal learning profile. | | Education and jargon | Assumes familiarity with developer work, commands, APIs, review, and later LLM/RAG concepts. | Add a task-specific glossary and explain the starting state before asking for execution. | | Religion | No substantial religious argument or evidence base is part of this book. | No religious-bias finding is warranted; don't invent one to fill an audit category. | | Invisible users | Support channels and customer councils omit some nonusers and people who abandoned. | Include unsuccessful and access-constrained participants when evaluating onboarding. | | Contributor belonging | C-008's mandatory solution rule can withhold standing from less-experienced reporters. | Accept observed failures; let the responsible team investigate remedies. | ### Multicultural transferability | Practice | Transferability judgment | Required local check | | --- | --- | --- | | Goal and prerequisite statement | Broadly adaptable as a method. | Is the task meaningful and the starting state attainable for this audience? | | Persona and interview | Conditional on recruitment and interpretation. | Do local participants recognize the described roles and constraints? | | F-pattern or left-to-right layout | Context-bound. | Test the actual language, direction, interface, and assistive technology. | | Plain language | Useful goal, not an English grade score exported unchanged. | Review terminology, translation, idiom, and comprehension in the target language. | | Video instruction | Conditional on bandwidth, hearing/vision access, language, and environment. | Provide a usable text/transcript route and captions where needed. | | Git-centered contribution | Depends on contributor skills and access. | Provide an issue/report path that doesn't require a complete patch. | | Organizational metrics | Depend on institution and user goal. | State whether the target is learning, task success, support load, or commercial adoption. | ### Accessibility findings in the supplied EPUB The package contains **37 image elements: 36 with nonempty alt and one with empty alt**. All 22 numbered instructional figures have nonempty alt. The empty-alt element is an author portrait; its appropriateness wasn't tested in a screen reader. Counts are structural facts, not an accessibility score. | Finding | Evidence | Impact / conclusion | | --- | --- | --- | | Wrong subject in diagram description | EPUB-C10#Fig1: sequential squares versus molecules/bands in alt. | Readers using that description receive unrelated information. Definite semantic defect. | | Added restriction in caution | EPUB-C03#Fig4: alt adds Corgi-only recording; pictured caution concerns dogs and permission. | The accessible text changes the instruction. Definite semantic defect. | | Wrong product name | EPUB-C03#Fig3: alt says “Corel Y” rather than Corg.ly. | Terminology differs across channels; confusion is possible. | | Nonempty text isn't enough | Every numbered figure has alt, including the defective ones. | A presence-only check would miss the above errors. | | Empty-alt guidance needs context | EPUB-C06#Par48 recommends body descriptions and explains blank alt. | Correct only where the image role and equivalent nearby information justify it. [W3C image decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/). | | Package claims aren't a conformance test | Accessibility metadata includes conformance claims and a warning about complex-diagram alternatives. | Neither metadata nor link checks resolve semantic errors or certify the reading experience. | **Not performed:** a screen-reader navigation session, keyboard audit in multiple reading systems, EPUBCheck/conformance certification, full contrast measurements, or a user study with disabled readers. The observed defects are enough to reject a blanket accessibility-pass claim; they don't quantify all remaining defects. ### Reading demands and supplementary perspectives **System estimate, not a measured grade score:** the explanatory prose is accessible to a motivated technical reader, roughly upper-secondary reading demands in many passages; the practical tasks require developer context and sometimes postsecondary technical knowledge. LLM, RAG, API, version control, release workflows, and analytics increase the knowledge burden. No standardized readability test or learner comprehension test was run. Chapter 9's suggested tenth-grade target shouldn't be mistaken for a measured level of this book. Supplement the book with disabled developers' observed task experiences, translators/localizers, maintainers with limited time, support staff who see failures, and beginners outside the product team. Recruit by relevant context and consent, not a presumed identity-to-behavior mapping. Use W3C's image guidance for the specific alt-text decision; it doesn't replace participation by readers who use the content. ## Prompt 10 — Notes pipeline within this file These notes remain sections of this canonical review. Suggested filenames are labels for a possible later promotion, not files created during this task. Existing notes are linked where they already own a related idea. ### Fleeting notes - **FN-01:** Does a current quickstart hide a token, permission, version, or installation assumption? Check one task before expanding process. Related Q10–Q11. - **FN-02:** Which failure reports are lost because the template asks for a fix? Compare C-008 and chapter 8's optional-solution field. - **FN-03:** Is a low-traffic page obsolete, or does it serve rare recovery? Don't decide from visits alone. Related Q22. - **FN-04:** Could an existing image-description check verify meaning, not just presence? Figure 10-1 supplies a concrete teaching case. - **FN-05:** What counts as actual agent consumption of a context file? File existence isn't enough. Related Q21. ### Literature notes | Note | Source-bound observation | Claim / quote / evidence | | --- | --- | --- | | LN-01 — Record the gap before choosing the fix | Chapter 1 defines a friction log through expected and actual experience, then distinguishes product fixes from documentation fixes. | C-003; EPUB-C01#Par130, #Par135; RW-440527299. | | LN-02 — Test the promised result | The accuracy pass asks: “If someone follows these instructions, will they get the result you promised them?” | C-007; EPUB-C04#Par25; RW-440527311. | | LN-03 — A sample has more than syntax | Chapter 5 distinguishes executable and explanatory samples. Its example timestamp fails calendar validation. The defect is this session's finding. | C-009; EPUB-C05#Par20, #PC2, #PC3; E03. | | LN-04 — Purpose precedes the metric | Chapter 9 distinguishes functional and structural quality and asks why measurement is needed and what decision follows. | C-015, C-018; EPUB-C09#Par20, #Par145–Par154; RW-440527345. | | LN-05 — Impact gives maintenance its scope | Chapter 11 begins planning with how users are affected, including whether functionality is new or changed. | C-024; EPUB-C11#Par20–Par24; RW-440527355, marked favorite. | | LN-06 — Generated text retains editorial obligations | Appendix B assigns quality responsibility to the producing team despite AI assistance. | C-028; EPUB-B#Par148; E12. | | LN-07 — Descriptions can contradict their images | The supplied EPUB's Figure 10-1 alt text describes a different subject from the diagram. This is an artifact observation, not an author recommendation. | C-012; EPUB-C10#Fig1; E06. | | LN-08 — Coordinated release needs substantive checks | Chapter 11's synchronization guarantee exceeds what timing can prove. | C-023; EPUB-C11#Par27; RW-440527356; system criticism. | ### Permanent-note candidates #### PN-01 — A documentation defect can originate in the product When a user can't finish a task, identify the failed step before prescribing more text. A missing explanation calls for documentation; a misleading error or impossible product action may require a software change. A friction log helps distinguish the two by preserving expected and actual behavior. This is a diagnostic method, not proof that a product change always has the larger payoff. Supports: [[#Literature notes|LN-01]], C-003. Existing connection: [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review]]. Suggested future filename: `A documentation defect can originate in the product.md`; consider improving the existing note before creating it. #### PN-02 — Documentation quality needs an explicit task A page can be polished yet fail because it omits a prerequisite. Define the reader's starting state and desired result before judging completeness. Then check whether the information supports that task, including finding it and recovering from expected failures. A task model can still omit users or conditions, so user research remains necessary. Supports: [[#Literature notes|LN-02 and LN-04]], C-001, C-015. Suggested future filename: `Documentation quality needs an explicit task.md`. #### PN-03 — Accessibility checks must compare meaning An image can have nonempty alt text and still communicate false information. Review whether the description preserves the image's relevant entities, relationships, constraints, and purpose. Structural checks can identify missing fields; they can't establish semantic equivalence by themselves. The supplied EPUB's sequence diagram illustrates that boundary. Supports: [[#Literature notes|LN-07]], C-012, E06. Suggested future filename: `Accessibility checks must compare meaning.md`. #### PN-04 — Generated reference inherits its source's errors Generation removes some copying work by deriving repeated facts from a shared source. It doesn't make the source correct or complete. Verify the specification and its relationship to runtime behavior separately from verifying that a generator ran. This applies to reference pages, example fixtures, and AI-assisted summaries, with different checks for each. Supports: [[#Literature notes|LN-03 and LN-06]], C-009, C-026, C-028. Suggested future filename: `Generated reference inherits its source errors.md`. #### PN-05 — Context availability isn't context consumption A context file can help only if the intended system receives and uses it for the task. File placement and readable structure are inputs; retrieval and correct behavior are separate outcomes. Test the actual consumer before treating a context convention as an assurance. Supports: C-020, C-032, E09. Existing connection: [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]]. Suggested future filename: `Context availability is not context consumption.md`; assess the existing note first. #### PN-06 — A release date doesn't prove a matching contract Publishing documentation and code together reduces timing drift. It doesn't establish that the documentation covers every user-visible change or that examples work. Release evidence therefore needs both coordination and a check of changed behavior against the stated instructions. Supports: [[#Literature notes|LN-08]], C-023. Suggested future filename: `A release date does not prove a matching contract.md`. ### Structure notes and attribution audit **Book map:** [[#Book map]] → [[#Chapter 1 — Understanding Your Audience]] through [[#Chapter 11 — Maintaining Documentation]] → [[#Claim-by-claim evaluation]]. **Theme map:** research and task scope (C-001–C-006); review and access (C-007–C-012); feedback and measurement (C-013–C-020); organization and maintenance (C-021–C-027); AI and provenance (C-028–C-032). **Project map:** use the experiment section for one existing documentation task; no project note is assumed missing. **Discipline map:** [[#Lineage and competing interpretations]]. **Unresolved map:** Q05, Q06, Q07, Q17, Q19, Q21, and Q23 remain research or local-testing boundaries even where a narrow conclusion is available. **Attribution check:** literature notes retain source locators; permanent candidates use original system wording; the timestamp and alt-text defects are identified as observed findings; third-party studies remain third-party; all earlier highlights retain their edition and IDs. The legacy personal-reflection voice isn't adopted as new reader testimony. No reciprocal links, new permanent-note files, or MOC edits are part of this session. ## Prompt 11 — Teaching pack **Audience:** developers, technical writers, DevRel practitioners, and maintainers revising one existing quickstart. **Prerequisites:** recognize the intended user task and read a short command/API example; provide a plain-language scenario for learners who don't write code. No access to the fictional Corg.ly service is required. ### Learning objectives By the end, a learner can define a task's starting state and outcome; choose an appropriate document type; identify one defect in each editing dimension; distinguish syntax, semantic data, and runtime validity; explain a misleading metric; and propose a scoped maintenance decision. Assess these through the produced artifacts, not attendance or self-reported confidence alone. **Key vocabulary:** friction log, prerequisite, tutorial, how-to, reference, functional quality, structural quality, semantic equivalence, denominator, and ownership. Use the controlled vocabulary above; introduce API and timestamp only when the exercise needs them. ### Lesson sequence — proposed 60-minute workshop | Time | Activity | Artifact and check | | --- | --- | --- | | 0–8 min | Define a reader, starting state, goal, and failure boundary. | A one-sentence task contract plus prerequisites. | | 8–18 min | Walk through a short quickstart without filling gaps silently. | Friction log with expected/actual behavior and evidence. | | 18–30 min | Apply the four editing questions in pairs. | At least one located finding; mark untested claims rather than inventing defects. | | 30–40 min | Examine the timestamp and image-description cases below. | Separate syntactic validity, data validity, and equivalent meaning. | | 40–50 min | Interpret the metrics case and choose a decision. | Rates with denominators; one alternative explanation; one follow-up check. | | 50–60 min | Propose a revision, review owner, and success/stop rule. | A bounded test plan and short reflection. | These are teaching allocations, not claimed task-completion timings or a schedule created for Courtney. ### Cases, activities, and answer key **Case A — plausible response, invalid date.** A response contains the string `2021-02-29T17:56:28.000Z`. Ask what can pass and what fails. **Answer:** it can be a legal JSON string, but it isn't a valid calendar date. Syntax checking, schema/type checking, semantic validation, and live-service behavior answer different questions. Don't ask learners to contact Corg.ly. Source: EPUB-C05#PC2; E03. **Case B — present alt text, wrong meaning.** Supply the verbal visual: eight boxes connected in a left-to-right sequence. Compare it with a description of lanes, bands, and molecules. **Answer:** the description fails equivalent meaning despite being nonempty. A concise replacement could describe the eight sequential nodes and connecting direction; exact detail should follow the diagram's purpose. Source: EPUB-C10#Fig1; E06. This replacement is a teaching proposal, not an edit to the EPUB. **Case C — support counts rose.** Fictional data: period A has 100 users and 20 support cases; period B has 200 users and 30 cases. **Answer:** total cases rise 50%, but cases per user fall from 0.20 to 0.15, a 25% decrease. Neither establishes a documentation effect: user mix, product changes, case severity, and exposure may differ. Ask what additional evidence would justify a decision. This is a system-created exercise, not a result reported in the book. **Case D — report without remedy.** A new developer can reproduce an inaccessible error message but doesn't know how to fix it. **Answer:** keep the observation, environment, and impact; assign investigation to an owner. A patch or suggested remedy isn't required to make the report valuable. Compare C-008 with C-014. ### Misconception checks and discussion | Statement | Expected response | | --- | --- | | Passing a prose linter means a quickstart works. | False; it checks configured patterns, not the whole task. | | A tutorial can guarantee success for everyone. | False; define and test supported prerequisites and conditions. | | Faster TTHW proves long-term adoption. | False; it measures one route to an initial result. | | An AGENTS.md file ensures an AI answer is grounded. | False; verify consumption, retrieval, and output separately. | | Disproving learning-style matching removes the need for alternatives. | False; access requirements and a matching hypothesis are different. | | The book's own defects make every recommendation invalid. | False; evaluate each claim and its evidence independently. | Discussion questions: whose task did the draft assume; what did the evaluator supply from prior knowledge; which finding belongs in the product; which metric could reward the wrong behavior; what evidence would change the proposed revision? Reflection: name one assumption you had to stop supplying for the reader, and one recommendation you narrowed after a counterexample. ### Assessment and facilitation Score five artifacts from 0–2 each: task contract, located/reproducible finding, appropriate revision, interpretable measurement, and review/stop rule. **0:** absent or unsupported; **1:** usable with a material gap; **2:** clear, sourced, and bounded. A proposed pass is 8/10 with no critical false claim such as “syntax proves the API works.” An oral explanation, annotated document, or text response can demonstrate the same objectives. This rubric is proposed, not validated against learner outcomes. Facilitators should distinguish the authors' workflow from the session's counterexamples and experimental suggestions. Don't teach visual-effect percentages or AI guarantees as settled facts. Offer accessible source text, equivalent diagram descriptions, captions for any demonstration, breaks or asynchronous completion, and flexible response formats. Avoid grading typing speed or familiarity with one operating system. Adapt examples, names, language, reading direction, and assumed infrastructure with learners; don't assign behaviors from nationality or disability labels. **Further reading:** chapter 1 for research, chapter 4 for review, chapter 9 for measurement, chapter 11 for maintenance; the linked W3C image decision tree for description choices; Diátaxis for content purposes; the two related vault book reviews for a next comparison. Those vault reviews remain secondary synthesis until their sources are reread. ## Prompt 12 — Actions and experiments All actions below are **recommendations or proposed tests**, not work already performed on another project. No automation, reminder, task-manager item, or commitment-ledger entry was created. ### Action inventory and PARA routing | Disposition | Action / scope | Route and reason | | --- | --- | --- | | Take next | Select one existing quickstart; state reader, version, prerequisites, and success output. | Projects, if attached to an actual active deliverable; don't create a project just for this suggestion. | | Take next | Record one bounded friction log and route each barrier to docs, product, or unresolved investigation. | The selected project's existing issue/report location; preserves action context. | | Consider after a trial | Add four review questions and an owner to the current writing workflow. | Areas, for an ongoing documentation responsibility, only after fit is tested. | | Consider when relevant | Validate example fixtures and image descriptions alongside their source content. | The existing repository or content process responsible for the example; not a new universal policy here. | | Avoid | Universal guarantees from sitemaps, AI context files, simultaneous releases, or readability scores. | Retain as negative knowledge in this review; don't copy unsupported assurances into guidance. | | More evidence needed | Whether AI assistance saves total effort without lowering quality. | A bounded experiment on an existing task; defer broad adoption. | | Conditional | User councils, many feedback channels, videos, sandboxes, or hiring. | Use only when audience need and maintenance capacity justify them. | | Preserve | Source-grounded concepts, evaluation, and teaching material. | This Archives review; link from Resources or Areas only when another task calls for it. | ### Two reversible experiments These are system-proposed designs. Review dates are candidate checkpoints assuming a start after this session; they aren't scheduled obligations. If no suitable task or participants are available, defer and reset the dates when the experiment starts. | Field | Experiment 1 — One task, four review questions | Experiment 2 — AI-assisted draft with full review cost | | --- | --- | --- | | Claims | C-003, C-007, C-009, C-015 | C-028, C-029, C-032 | | Hypothesis | A task-focused revision removes observed barriers for the intended users. | Assistance reduces total authoring-plus-review effort without increasing material errors. | | Action | Capture a baseline on one supported quickstart; revise located failures; repeat with comparable, consenting unfamiliar readers. | Use two short, comparable documentation tasks with a fixed source packet and acceptance criteria; compare manual and assisted routes and include verification time. | | Measures | Completion/failure counts, failure step, prerequisites, environment, assistance required, and time among completed attempts. | Total active minutes, factual/version errors, reviewer corrections, unsupported claims, and task acceptance. Record task differences. | | Duration | Up to two weeks after a suitable task is selected; initial small rounds are formative, not representative. | Up to two weeks after the first experiment or another suitable task; no population productivity estimate. | | Stop condition | Stop a run when a missing prerequisite, unavailable service, accessibility blocker, or unexpected external side effect prevents the declared task; classify it before continuing. Stop the experiment after two revision rounds or if comparable conditions can't be established. | Stop if source provenance can't be checked, material facts remain unsupported after one review cycle, or the effort cap of 90 active minutes per route is reached. Record the incomplete result. | | Review date | Proposed 2026-10-04, if started this week. | Proposed 2026-10-18, if a suitable comparison is available. | | Adoption rule | Keep the revision when the observed blocker no longer reproduces and no material regression appears; document who and what was tested. | Adopt for that task class only if both outputs pass the same checks and total effort falls enough to matter locally; record the actual difference rather than selecting a percentage in advance. | **Decision rules:** adopt a supported local improvement; adapt when one cohort or environment still fails; test further when task differences or sample selection confound the result; reject a change that adds material error or access barriers; defer when no meaningful comparison or owner exists. A two-task result doesn't justify a universal AI policy. No experimental outcome is claimed here. ### Drift monitoring plan | Topic | What can change / source | Frequency and reassessment | Early-review trigger | | --- | --- | --- | --- | | AI context consumption | Agent loaders, discovery rules, and retrieval behavior; actual runtime plus official format/tool documentation. | At implementation and quarterly if used; candidate 2026-12-20. | Agent/version changes or a task ignores supplied context. | | AI workflow value | Capabilities, cost, privacy settings, review burden; task-level measurements and current vendor docs. | Each pilot or model change; candidate 2026-12-20. | New unsupported claims, data-handling change, or review cost reversal. | | Search behavior | Crawl/index rules and URL migrations; Google Search Central and the site's verified indexing evidence. | Before a migration; reassess by 2027-09-20 if still relied on. | Indexed pages disappear or crawler access changes. | | Code examples | API versions, dependencies, credentials, and response schemas; owned code/specifications and tests. | At relevant releases, not just annually. | Supported behavior or prerequisite changes. | | Accessibility | Reading system, media, alternative text, and content structure; actual rendered artifact and user checks. | With changed media or rendering; candidate 2026-12-20 for a chosen artifact. | A description/visual mismatch or an access report. | | Resource recommendations | Courses, services, communities, and disclosed affiliations. | Check before spending time or money; resource list expires as current advice on 2027-09-20. | Broken link, changed ownership, cost, or availability. | ## Prompt 13 — Visual thinking pack The diagrams remain embedded in this one Markdown file. Color follows the vault convention: green thesis, blue concepts, orange takeaways, purple connections. Labels and text equivalents carry meaning independently of color. These are system-designed representations of the analysis, not reproduced figures from the book. ### Visual 1 — Claim dependency and argument map **Purpose:** show how user research, content checks, publication, and maintenance connect. **Nodes/connections/grouping/layout:** the top-down Mermaid graph under Prompt 4 groups foundations, content, checks, learning, and maintenance; a dashed side node isolates overclaims. **Labels:** claim IDs remain visible. **Uncertainty:** arrows describe a reconstructed workflow, not measured causation. **Sources:** C-001, C-004, C-006, C-007, C-009, C-012–C-015, C-018, C-021, C-024, C-027; RW-440527299, RW-440527311, RW-440527326, RW-440527345, RW-440527355. Text equivalent: research defines the task; the task shapes content; checks assess it against purpose; publication exposes it to use; feedback informs maintenance and renewed research. Indexing, AI-understanding, synchronization, and launch-date overclaims stand outside the necessary chain. ### Visual 2 — Evidence-aware revision decision **Purpose:** route an observed failure without prescribing documentation for every problem. **Grouping/layout:** top-down decisions, ending in orange actions. **Sources:** C-003, C-009, C-012, C-014, C-018; RW-440527299, RW-440527326, RW-440527332. **Uncertainty:** a failure may involve more than one cause; the “unknown” route prevents premature attribution. ```mermaid flowchart TD OBS["Record task, environment, expected and actual result"] --> REP{"Can the barrier be reproduced?"} REP -->|No| CONTEXT["Gather missing context"] REP -->|Yes| CAUSE{"What blocks the task?"} CAUSE -->|Missing or wrong information| DOC["Revise and test the documentation"] CAUSE -->|Product behavior| PROD["Route a product issue; explain a supported workaround if needed"] CAUSE -->|Access barrier| ACCESS["Repair access and test equivalent meaning"] CAUSE -->|Unknown or mixed| INVEST["Investigate without assigning a cause"] DOC --> VERIFY["Repeat task; record failures and side effects"] PROD --> VERIFY ACCESS --> VERIFY classDef thesis fill:#d9ead3,stroke:#38761d,color:#172517; classDef concept fill:#d9eaf7,stroke:#285f8f,color:#132b40; classDef action fill:#fce5cd,stroke:#a65d12,color:#40240a; class OBS thesis; class REP,CAUSE concept; class CONTEXT,DOC,PROD,ACCESS,INVEST,VERIFY action; ``` Text equivalent: reproduce the barrier first. Missing information suggests a documentation change; product behavior suggests a product issue; access failure requires an access repair; uncertain causes require investigation. Repeat the task after any proposed remedy. ### Visual 3 — Proposed maintenance feedback loop **Purpose:** distinguish a plausible improvement loop from confounding changes in demand. **Nodes:** actionable reports, relevant revisions, barriers, user exposure, raw reports. **Connections:** signed arrows indicate a proposed direction while other factors remain fixed. **Grouping/layout:** vertical feedback loop with an external exposure branch. **Sources:** C-014, C-018, C-024, C-025; RW-440527331, RW-440527344, RW-440527355. **Uncertainty:** reporting propensity, product changes, and staffing can reverse observed counts; the loop isn't empirically estimated. ```mermaid flowchart TD B["Task barriers"] -->|"+ with stable reporting"| R["Actionable reports"] R -->|"+ with capacity"| F["Relevant fixes"] F -->|"- if effective"| B U["User exposure"] -->|"+ independently of quality"| RAW["Raw report count"] B -->|"+ if detected"| RAW RAW -.->|"Interpret with denominators and context"| R classDef concept fill:#d9eaf7,stroke:#285f8f,color:#132b40; classDef action fill:#fce5cd,stroke:#a65d12,color:#40240a; classDef connection fill:#eadcf4,stroke:#744394,color:#2e193b; class B,R concept; class F action; class U,RAW connection; ``` Text equivalent: more barriers can produce more actionable reports; with capacity, those reports can produce fixes; effective fixes reduce barriers. More users can increase total reports independently of quality, so raw counts can't establish whether the loop improved anything. ### Visual 4 — Excalidraw front and back specification **Title:** “Docs that support a tested task.” **Purpose:** a scannable book map with evidence and decisions available on the back. This is an implementation-ready specification, not a separate Excalidraw file. Use two 1600 × 1000 frames, front at x=0 and back at x=1800, both y=0. Leave 80-pixel margins, use 28-pixel frame titles and at least 20-pixel body text, and keep approximately 40 pixels between cards. Use rectangular cards with 16-pixel padding; use stroke, label, and shape distinctions as well as color. | Frame / placement | Nodes and labels | Connections / grouping | | --- | --- | --- | | Front, top at (80, 80), 1440 × 120 | Green thesis: “Define the reader's task; verify the result.” C-001, C-015. | Central title spans all three columns. | | Front, left at (80, 260), 430 × 420 | Blue “Discover and shape”: chapters 1–3; audience → task → content type → outline. | Arrow to middle; RW-440527299, RW-440527303. | | Front, middle at (580, 260), 430 × 420 | Blue “Make it work”: chapters 4–6; four review questions, examples, equivalent visual meaning. | Arrow to right; RW-440527311, RW-440527318, RW-440527322. | | Front, right at (1080, 260), 440 × 420 | Orange “Publish and sustain”: chapters 7–11; release → feedback → measurement → organization → maintenance. | Return arrow to left labeled “Changed tasks and evidence”; RW-440527326, RW-440527345, RW-440527355. | | Front, bottom at (80, 760), 1440 × 140 | Purple “AI changes production and retrieval; it doesn't remove verification.” Appendix B; C-028–C-032. | Dotted connections to content review and maintenance. | | Back, left at (1880, 180), 680 × 540 | Evidence table: source claim → expected test → observed result → remaining limit. Include timestamp and alt-text cases. | Links by claim/evidence ID to C-009/E03 and C-012/E06. | | Back, right at (2640, 180), 680 × 540 | Decision cards: keep methods; narrow guarantees; run one task trial; compare total AI review cost. | Orange cards cite C-003, C-007, C-019, C-020, C-023, C-029. | | Back, bottom at (1880, 780), 1440 × 120 | Idea Compass with four labeled quadrants. | Purple links to related concepts and existing notes, described below. | **Idea Compass:** Parents — user-centered technical communication and [[4. Archives/Book reviews/Letting Go of the Words|Letting Go of the Words]]; Children — the six permanent-note candidates and two proposed experiments in this file; Friends — [[4. Archives/Book reviews/The Product is Docs|The Product is Docs]] and [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure|Documentation Is Dual-Audience Infrastructure]]; Competitors — feature-first inventories, traffic-as-quality, and automation-without-verification as alternative approaches to examine, not authors to dismiss. **Uncertainty labels:** “fictional worked example,” “historical company case,” “local test,” “current primary guidance,” and “unmeasured local outcome.” Keep them on evidence cards so a vivid image can't hide the strength of support. Don't copy icons into the frame; use text labels and links. The evidence ledger and lineage table supply the requested evidence map and comparison matrix. A separate timeline or stakeholder graph would repeat material without answering another question, so neither is added. ## Layer 1 — Readwise highlights These are the **76 verbatim source records from the earlier Kindle edition**, ordered by Kindle location. No second-edition page number is assigned to them. Global metadata: Readwise book ID 22380269; source Kindle; ASIN B09HLZGWKT; book tag `Dev Work`; no book document note. Each `RW-` suffix is the native highlight ID. All reader-note fields are empty. Timestamps are preserved in UTC as returned, not inferred from local note dates. The near-duplicate linter passages remain separate records so their different locations, spacing, and dates survive. See the ingestion summary for their single normalized-passage grouping. The appendix is collapsed for scanning; expanding it reveals every source highlight. <details> <summary>Show all 76 earlier-edition highlights</summary> ### RW-440527290 **Location:** 579 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.953834Z` · **Reader note:** empty · **Highlight URL:** not supplied > In the late 1980s, a group of economists at Harvard determined that humans assume others have the same knowledge they do. They named this cognitive bias the “curse of knowledge.” ### RW-440527291 **Location:** 592 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.953888Z` · **Reader note:** empty · **Highlight URL:** not supplied > This chapter guides you through breaking the curse of knowledge and understanding your users by: Identifying the goals you have for your users Understanding who your users are Understanding your users’ needs and how documentation addresses them Condensing your findings into personas, stories, and maps Testing your assumptions with a friction log ### RW-440527292 **Location:** 628 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.953922Z` · **Reader note:** empty · **Highlight URL:** not supplied > Developer skill Programming languages Developer environment Operating system Team role A list of characteristics gives you a starting point for user research. You can add more categories later as your research progresses. ### RW-440527293 **Location:** 633 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.953954Z` · **Reader note:** empty · **Highlight URL:** not supplied > Some questions, in general, apply to all products. Questions like: What is this product? Will this product solve my problem? What features are available? How much does it cost? How do I get started? ### RW-440527294 **Location:** 635 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.953987Z` · **Reader note:** empty · **Highlight URL:** not supplied > Other questions are going to be very specific to your product, your users, and their goal: How do I authenticate against your API? How do I use a specific feature? How do I troubleshoot a specific problem? ### RW-440527295 **Location:** 654 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954019Z` · **Reader note:** empty · **Highlight URL:** not supplied > Developer relations Product support User experience Marketing ### RW-440527296 **Location:** 696 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954050Z` · **Reader note:** empty · **Highlight URL:** not supplied > Note Consider the diversity of the people you talk to. Look at the age, gender, disabilities, ethnicity, job duties, and social and economic status of your pool. Are your interview participants representative of the wider group of people who will eventually read your documentation? ### RW-440527297 **Location:** 725 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954081Z` · **Reader note:** empty · **Highlight URL:** not supplied > Three useful ways of condensing your user research findings are: User personas User stories User journey maps ### RW-440527298 **Location:** 727 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954112Z` · **Reader note:** empty · **Highlight URL:** not supplied > A user persona is a semi-fictional character created to represent your ideal reader or readers. This character can be based on a specific person or an amalgam of people you learned about in your research. A user persona usually includes a short description of the individual (real or imagined) and a list of their goals, skills, knowledge, and situation. ### RW-440527299 **Location:** 781 (Kindle location) · **Provisional group:** 1 — Audience · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954145Z` · **Reader note:** empty · **Highlight URL:** not supplied > A friction log is a journal in which you try your software as a user would and record your experiences. To record your experience, log each step sequentially, noting the behavior you expect and the actual behavior of your software. The bigger the gap between expectation and reality, the bigger the opportunity to improve your docs or software. ### RW-440527300 **Location:** 862 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954176Z` · **Reader note:** empty · **Highlight URL:** not supplied > A use case (also called a business problem or user scenario) is a set of tasks required to complete a goal. Each task is an interaction with your service or systems. You can create use cases from researching your users and finding what goals are most important to them. When you identify the most important use cases for your users, you can plan your documentation with content types that address their needs. Good documentation describes use cases that help your users meet their goals. ### RW-440527301 **Location:** 889 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954207Z` · **Reader note:** empty · **Highlight URL:** not supplied > A README is a single text file, often written in Markdown, that summarizes a collection of code, usually at the top level of the code repository.2 You can also write READMEs for important subfolders that require additional summary or explanation. A README contains basic information like: What the code does at a high level How to install it Troubleshooting steps Who maintains the code License information A changelog Basic examples Links to more in-depth resources and documentation ### RW-440527302 **Location:** 907 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954238Z` · **Reader note:** empty · **Highlight URL:** not supplied > As you write a getting started document, some questions you should ask yourself are: What are the quickest explanations of what this service is and what its core features do? What are the simplest steps to install and use your product? What are the most important questions new users will have? What are the cool things they can do with your service? ### RW-440527303 **Location:** 937 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954269Z` · **Reader note:** empty · **Highlight URL:** not supplied > Procedural content includes tutorials and how-to guides—anything from installation instructions to API integrations. A procedural document shows readers how to accomplish a specific goal by following a set of structured steps. A single step should describe a single action that a user takes. ### RW-440527304 **Location:** 982 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954299Z` · **Reader note:** empty · **Highlight URL:** not supplied > Links in the middle of your document may distract readers. Instead, provide links to additional resources at the bottom of the page. ### RW-440527305 **Location:** 1007 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954330Z` · **Reader note:** empty · **Highlight URL:** not supplied > Any complex system has terms with unclear meanings. A glossary is a collection of terms and definitions that are specific to your service, field, or industry. ### RW-440527306 **Location:** 1036 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954361Z` · **Reader note:** empty · **Highlight URL:** not supplied > A changelog provides a helpful historical record for internal teams like support and engineering. ### RW-440527307 **Location:** 1044 (Kindle location) · **Provisional group:** 2 — Planning · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954392Z` · **Reader note:** empty · **Highlight URL:** not supplied > Release notes are another helpful type of documentation. Release notes provide rich context for the changes listed in a changelog. While a changelog can be automated or consist only of a bulleted list with little context, release notes speak directly to your users. Here's the change that took place. Here's why. Here's how it used to be. Here's how it's going to be. Release notes give users context to understand why a change took place. ### RW-440527308 **Location:** 1158 (Kindle location) · **Provisional group:** 3 — Drafting · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954423Z` · **Reader note:** empty · **Highlight URL:** not supplied > You can start your document by listing the information you’ve already gathered at the top: Audience Purpose Pattern ### RW-440527309 **Location:** 1234 (Kindle location) · **Provisional group:** 3 — Drafting · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954454Z` · **Reader note:** empty · **Highlight URL:** not supplied > A procedure is a sequential set of actions a reader takes to achieve a desired result. Procedures should always use numbered lists to help readers understand the order of tasks they’re performing. Explain the desired goal at the start of the procedure so that users understand what they are doing. At the end of the procedure, add a way for the user to check that they performed it correctly. ### RW-440527310 **Location:** 1420 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954485Z` · **Reader note:** empty · **Highlight URL:** not supplied > Like code reviews, editing is a collaborative process, where you share your content with others, test your assumptions, and gather feedback. This may feel vulnerable at first, but it’s also where the most learning happens. As you integrate the feedback you receive, you may see more elegant ways to approach the problem you’re documenting and write more effectively. ### RW-440527311 **Location:** 1436 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954516Z` · **Reader note:** empty · **Highlight URL:** not supplied > When editing for technical accuracy, you’re editing for the correctness of your content. You should be able to answer the following questions: If someone follows these instructions, will they get the result you promised them? Is there any technical jargon or terms that might lead to confusion? Are code functions, parameters, and endpoints named and explained correctly? ### RW-440527312 **Location:** 1455 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954557Z` · **Reader note:** empty · **Highlight URL:** not supplied > Editing for completeness is a great time to involve a new reader. New readers often see the gaps in your explanations and instructions far more quickly than you do. ### RW-440527313 **Location:** 1465 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954588Z` · **Reader note:** empty · **Highlight URL:** not supplied > As you edit for structure, you’re trying to answer the following questions: Is it clear from the title and headers what the document is about? Is the document organized in a consistent and logical way? Are there sections in this document that should be put in another document? If a template exists, does the document follow it? ### RW-440527314 **Location:** 1485 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954619Z` · **Reader note:** empty · **Highlight URL:** not supplied > As you read each section of your document, ask yourself the following: Is this as clear as it can be? Are there terms used inconsistently that I should correct? Are there unnecessary words or phrases that I can cut? Are there any idioms, metaphors, or slang that could confuse readers? Am I using any biased language that should be avoided? ### RW-440527315 **Location:** 1558 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954649Z` · **Reader note:** empty · **Highlight URL:** not supplied > You may only criticize an idea if you also add a constructive suggestion. ### RW-440527316 **Location:** 1561 (Kindle location) · **Provisional group:** 4 — Editing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954680Z` · **Reader note:** empty · **Highlight URL:** not supplied > Constructive suggestions provide additional context for what you think would solve the problem. ### RW-440527317 **Location:** 1644 (Kindle location) · **Provisional group:** 5 — Code samples · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954711Z` · **Reader note:** empty · **Highlight URL:** not supplied > A good code sample should be: Explained: It’s displayed alongside a written description, whether in the main body of text or in code comments to provide context and explanation where needed. Concise: It provides the exact amount of information needed by the reader. Clear: It follows conventions a reader would expect of the language the sample is written in. ### RW-440527318 **Location:** 1648 (Kindle location) · **Provisional group:** 5 — Code samples · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954742Z` · **Reader note:** empty · **Highlight URL:** not supplied > Executable code should also be: Usable (and extensible): It’s clear how the reader uses the sample and where they need to input their own data. Trustworthy: It’s pastable, works, and only does what a reader expects. ### RW-440527319 **Location:** 1791 (Kindle location) · **Provisional group:** 5 — Code samples · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954773Z` · **Reader note:** empty · **Highlight URL:** not supplied > Make sure your samples are: Explained: Provide the why, not the what, behind your sample. Concise: Aim for minimal reproducible examples. Clear: Lean on existing conventions and style guides. Extensible: Make it clear where and how a reader needs to amend their own code. Trustworthy: Be consistent and test, test, and test again. ### RW-440527320 **Location:** 1851 (Kindle location) · **Provisional group:** 6 — Visuals · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954804Z` · **Reader note:** empty · **Highlight URL:** not supplied > Like written documentation, the most effective visual content is something the reader barely notices. It doesn’t require them to stop in order to think or be aware of the fact they are consuming anything at all. ### RW-440527321 **Location:** 1869 (Kindle location) · **Provisional group:** 6 — Visuals · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954836Z` · **Reader note:** empty · **Highlight URL:** not supplied > Ineffective visual content interferes with the transfer of information, usually due to a lack of: Comprehension Accessibility Performance ### RW-440527322 **Location:** 1899 (Kindle location) · **Provisional group:** 6 — Visuals · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954867Z` · **Reader note:** empty · **Highlight URL:** not supplied > If you think a screenshot would be useful to your readers, make sure they: Never appear without introduction or reference in the text. Appear close to the instructions or related text. Are clean and clutter free—do not include anything in your screenshot not part of your UI. Include all relevant parts of the UI with enough context to reassure the reader they’re on the right screen. Not too big—your readers need to be able to read all parts of the image. Not too small—your readers need to be able to correlate the screenshot to the UI they experience. ### RW-440527323 **Location:** 1917 (Kindle location) · **Provisional group:** 6 — Visuals · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954898Z` · **Reader note:** empty · **Highlight URL:** not supplied > There are several types of process diagrams that are particularly helpful in documentation: Boxes and arrows Flowcharts Swimlanes ### RW-440527324 **Location:** 2098 (Kindle location) · **Provisional group:** 7 — Publishing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954929Z` · **Reader note:** empty · **Highlight URL:** not supplied > Building a content release process Creating a publishing timeline Finalizing and approving publication Announcing your content to your audience ### RW-440527325 **Location:** 2103 (Kindle location) · **Provisional group:** 7 — Publishing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954960Z` · **Reader note:** empty · **Highlight URL:** not supplied > Your content release process should answer the following questions: When are you going to publish your content? Who is responsible for final review and publication? Where are you going to publish your content? What additional software tools are needed to publish the content? How will you announce your new content to your users? ### RW-440527326 **Location:** 2140 (Kindle location) · **Provisional group:** 7 — Publishing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.954992Z` · **Reader note:** empty · **Highlight URL:** not supplied > Test your docs, even if they’re not part of your codebase. If you don’t have unit tests for code samples, test instructions manually. ### RW-440527327 **Location:** 2157 (Kindle location) · **Provisional group:** 7 — Publishing · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955023Z` · **Reader note:** empty · **Highlight URL:** not supplied > To meet your users where they are, consider the following questions and scenarios: Are they internal teams looking for the right way to use something in your organization? A private wiki or an intranet site is a good place to put it. Are your readers external users who work with code or endpoints? It’s convenient for them if the documentation is in the same repository as the code. Are your readers end users or system administrators looking to install something? Make sure the documents are external to the software to avoid a dependency loop. Are your readers external users of your codebase? Put it on your website or in your code repository. ### RW-440527328 **Location:** 2239 (Kindle location) · **Provisional group:** 8 — Feedback · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955054Z` · **Reader note:** empty · **Highlight URL:** not supplied > There are many creative ways to gather feedback from your users. For the purposes of this chapter, we focus on these channels that relate closely to documentation: Accepting feedback directly through documentation pages Monitoring support issues Collecting document sentiment Creating user surveys Creating a user council ### RW-440527329 **Location:** 2268 (Kindle location) · **Provisional group:** 8 — Feedback · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955086Z` · **Reader note:** empty · **Highlight URL:** not supplied > Document sentiment is how readers feel about your documentation. You can discover and measure document sentiment through a simple survey or by using embedded code on a page that prompts a user to indicate by clicking a simple yes or no whether the page was helpful ### RW-440527330 **Location:** 2285 (Kindle location) · **Provisional group:** 8 — Feedback · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955118Z` · **Reader note:** empty · **Highlight URL:** not supplied > How satisfied are you with Corg.ly’s documentation?   2. Are you able to find the information you were looking for?   3. How much time did it take you to find this information?   4. Did this effort match your expectations?   5. What can we do to improve our documentation? ### RW-440527331 **Location:** 2314 (Kindle location) · **Provisional group:** 8 — Feedback · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955149Z` · **Reader note:** empty · **Highlight URL:** not supplied > Each feedback issue should be quickly evaluated to see if you can answer the following questions: 1. Is the issue valid?   2. Can it be fixed?   3. How important is the issue?   The following sections dive into each of these questions, defining specific requirements for answers at each step. Answering these questions helps you separate actionable user feedback from feedback that needs more information and feedback that can be ignored. Applying a standard triage process is critical because it:3 Speeds up the response times to user issues Prevents requested work from lingering endlessly Builds a standard set of priorities for issues Directs limited resources toward the most necessary and impactful changes ### RW-440527332 **Location:** 2334 (Kindle location) · **Provisional group:** 8 — Feedback · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955179Z` · **Reader note:** empty · **Highlight URL:** not supplied > For a documentation issue to be actionable, it must be: Original Reproducible Scoped ### RW-440527333 **Location:** 2424 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955209Z` · **Reader note:** empty · **Highlight URL:** not supplied > If a document is good when it fulfills its purpose, then what is its purpose? The purpose of your documentation should align with the purpose of your code: to drive specific user behavior and accomplish the goals of your organization. ### RW-440527334 **Location:** 2427 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955243Z` · **Reader note:** empty · **Highlight URL:** not supplied > Functional quality, which describes whether or not a document accomplishes its purpose or goal Structural quality, which describes whether a document is well written and well structured ### RW-440527335 **Location:** 2433 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955273Z` · **Reader note:** empty · **Highlight URL:** not supplied > The functional quality of documentation can be broken down into the following categories:2 Accessible Purposeful Findable Accurate Complete ### RW-440527336 **Location:** 2472 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955304Z` · **Reader note:** empty · **Highlight URL:** not supplied > Findability is the measure of how easily your readers navigate to and through your content. ### RW-440527337 **Location:** 2487 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955334Z` · **Reader note:** empty · **Highlight URL:** not supplied > Accuracy is the measure of how correct and credible the content is in a document. ### RW-440527338 **Location:** 2495 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955365Z` · **Reader note:** empty · **Highlight URL:** not supplied > A document is complete if it contains all of the information necessary for the reader to succeed. For a task-driven document, completeness means: 1. Listing all prerequisites that readers should follow.   2. Documenting all tasks required to finish the task.   3. Defining next steps the reader should take. ### RW-440527339 **Location:** 2505 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955395Z` · **Reader note:** empty · **Highlight URL:** not supplied > This book uses the “three Cs” of good writing to define structural quality: Clear Concise Consistent ### RW-440527340 **Location:** 2508 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955425Z` · **Reader note:** empty · **Highlight URL:** not supplied > clear documentation has: Well-defined and well-ordered headers that break down a topic into logical sections Headers ordered chronologically for tasks and each step indicating the desired outcome Unambiguous results for each step in a process Steps organized in a way your readers understand Content that calls out any places where a reader might get stuck Definitions of any errors that users may encounter ### RW-440527341 **Location:** 2552 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955455Z` · **Reader note:** empty · **Highlight URL:** not supplied > Organizational goals are specific behaviors the organization wants from its users. ### RW-440527342 **Location:** 2555 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955486Z` · **Reader note:** empty · **Highlight URL:** not supplied > Recruiting and onboarding new users Encouraging existing users to adopt new features Getting users to complete a specific task Retaining existing users Addressing users’ support needs and product questions ### RW-440527343 **Location:** 2589 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955515Z` · **Reader note:** empty · **Highlight URL:** not supplied > Documentation metrics you can collect include: Unique visitors: Unique visitors are the number of people who have visited your site over a set period of time. Page views: A page view records each time a visitor looks at a page. Page views help you understand which of your pages are visited most, least, or not at all. Time on page: Time on page tracks the amount of time a visitor spends on your page before moving on to the next one. Bounce rate: Bounce rate is the number of visitors who come to your site, visit one page, and then leave (“bounce”) without viewing other pages. Search keyword analysis: Keyword analysis shows you the search terms visitors use to enter your site. It can help you understand whether you’re providing the information your users are looking for. Reading level or text complexity analysis: Reading level or text complexity analysis helps you understand how difficult your pages are to read and understand. Support issues related to documentation: Tracking support issues related to documentation helps you understand where documentation fails to meet your user’s needs. Link validation: Link validation evaluates whether links to and from pages on your site are broken. Broken links are a common source of user frustration. Time to Hello World (TTHW): Time to Hello World is the amount of time it takes a developer to author “Hello World” in a new programming language or to accomplish a fairly simple task with your service. ### RW-440527344 **Location:** 2618 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955545Z` · **Reader note:** empty · **Highlight URL:** not supplied > When evaluating the quality of your content with documentation metrics, keep the following tips in mind: Make a plan Establish a baseline Consider context Use clusters of metrics Mix qualitative and quantitative feedback ### RW-440527345 **Location:** 2624 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955575Z` · **Reader note:** empty · **Highlight URL:** not supplied > Why do you want to measure? What will you do with the information? How will your effort advance the goals of your organization? ### RW-440527346 **Location:** 2628 (Kindle location) · **Provisional group:** 9 — Quality · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955604Z` · **Reader note:** empty · **Highlight URL:** not supplied > baseline allows you to compare metrics before and after you’ve made changes so you can evaluate their impact. ### RW-440527347 **Location:** 2728 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955634Z` · **Reader note:** empty · **Highlight URL:** not supplied > Planning your information architecture, and helping your readers build a mental model of your content means incorporating new elements into your set of documentation, including: Site navigation and organization Landing pages Navigation cues ### RW-440527348 **Location:** 2769 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955664Z` · **Reader note:** empty · **Highlight URL:** not supplied > Landing pages are pages that route users to the right content with minimal reading required, building trust with users by saving them time. ### RW-440527349 **Location:** 2794 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955693Z` · **Reader note:** empty · **Highlight URL:** not supplied > Navigation cues include elements like: Breadcrumbs that show where a particular page sits in a content hierarchy by displaying its parent pages Side navigation that shows the content hierarchy for the entire site, or a large portion of the site Labels and metadata that contain information relevant to the document, typically machine readable for help with search indexing Prerequisites, next steps, and additional information sections that are succinct and informative, directing users where to go next, or what they should have read before arriving at a page Escape hatches, often in the form of callouts, that offer recommendations for alternative pages if a reader ends up on the wrong page ### RW-440527350 **Location:** 2814 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955722Z` · **Reader note:** empty · **Highlight URL:** not supplied > Next, evaluate each page in the list, using what you know about your users to determine how well each page is working. Ask yourself the following questions: Is this page useful? Is this page up to date? Is this page in the right place? As you evaluate each page, label it with what work needs to be done. Example labels include: Keep Remove Review for accuracy Merge with another document Split into multiple documents ### RW-440527351 **Location:** 2818 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955752Z` · **Reader note:** empty · **Highlight URL:** not supplied > ask yourself, is there missing information that your users have been requesting? This missing content is called a content gap ### RW-440527352 **Location:** 2826 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955782Z` · **Reader note:** empty · **Highlight URL:** not supplied > Ultimately, users expect your content to be: Consistent: Your content is organized with familiar structure and patterns. Users always know where they are. Relevant: The most important content that addresses the most common user needs is the easiest to find. Findable: Your content is easily accessed from any homepage or landing pages, and through search. ### RW-440527353 **Location:** 2851 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955812Z` · **Reader note:** empty · **Highlight URL:** not supplied > you move the pages around, use this validation checklist as an auditing mechanism: Landing pages: created sparingly and guiding users to the most important documents Content types: consistently implemented and suitable for your users Page data: descriptive and consistent titles, headers, prerequisites, and next steps Navigation cues: breadcrumbs, side navigation, and escape hatches to help orient users Labels and metadata: display relevant data for users and search index Redirects: users are redirected from previous locations to new URLs after you move pages ### RW-440527354 **Location:** 2860 (Kindle location) · **Provisional group:** 10 — Organization · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955842Z` · **Reader note:** empty · **Highlight URL:** not supplied > When you add new pages to your documentation, consider the following questions: Is it clear where this new content belongs? What adjustments to the existing information architecture are required? Does this content impact the home page and landing pages? ### RW-440527355 **Location:** 2926 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** favorite **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955872Z` · **Reader note:** empty · **Highlight URL:** not supplied > Start your plan by considering how your users are impacted and answering the following questions: How are users impacted by this change? How does this change affect existing product functionality? What existing documentation does this change affect? What new documentation do we need to create to support our users? ### RW-440527356 **Location:** 2936 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955903Z` · **Reader note:** empty · **Highlight URL:** not supplied > Once you’ve budgeted time in your planning process for updating documentation, you should also integrate documentation into your release process. Updated documentation and code should be released at the same time, guaranteeing that they both stay in sync. ### RW-440527357 **Location:** 2944 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955932Z` · **Reader note:** empty · **Highlight URL:** not supplied > A tracking spreadsheet lists all proposed enhancements for the upcoming release.   2. Each proposed enhancement is documented in a Github Issue, and is required to have a design doc, feature owner, unit tests, and an assessment of whether or not documentation is necessary.   3. If the enhancement needs documentation, the feature owner must open a Pull Request for documentation and receive approval before the enhancement is approved for release.   4. Once the code, unit tests, and documentation are all approved for the enhancement, the enhancement is approved for launch.   5. On the release date, all approved enhancements are pushed with the new release. ### RW-440527358 **Location:** 2998 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955963Z` · **Reader note:** empty · **Highlight URL:** not supplied > Link checkers work in one of two ways: By running against your documentation prior to publication as part of your CI/CD toolchain By running against the documentation after it’s published by crawling your document like a web page ### RW-760358744 **Location:** 3002 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2024-08-20T04:56:00Z` · **Record updated:** `2024-08-20T01:54:56.318459Z` · **Reader note:** empty · **Highlight URL:** not supplied > Documentation linters, or prose linters, operate on the same principle as code linters. They can find, flag, and propose fixes to common issues found in documentation. Prose linters are similar to the spelling and grammar checker included with most word processors, such as when your spellchecker catches misspellings of common words. ### RW-440527359 **Location:** 3013 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.955992Z` · **Reader note:** empty · **Highlight URL:** not supplied > Documentation linters , or prose linters, operate on the same principle as code linters. They can find, flag, and propose fixes to common issues found in documentation. Prose linters are similar to the spelling and grammar checker included with most word processors, such as when your spellchecker catches misspellings of common words. ### RW-440527360 **Location:** 3039 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.956022Z` · **Reader note:** empty · **Highlight URL:** not supplied > As a rule, documentation should be deleted when it’s no longer useful to your users. There are a few common reasons this might happen. One is when all the users of a deprecated feature have successfully migrated away from it, the feature is being removed, and the documentation is no longer needed. Another reason to delete is when a piece of documentation is outdated or irrelevant and it’s not worth the time to fix it. ### RW-440527361 **Location:** 3057 (Kindle location) · **Provisional group:** 11 — Maintenance · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.956052Z` · **Reader note:** empty · **Highlight URL:** not supplied > Plan code and documentation together with maintainability in mind. Align documentation releases with feature releases. Assign owners to documents. Automate toil with content freshness checks, link checkers, documentation linters, and reference doc generators—but be careful before automating. ### RW-440527362 **Location:** 3116 (Kindle location) · **Provisional group:** Additional resources · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.956082Z` · **Reader note:** empty · **Highlight URL:** not supplied > Technical Writing Courses from Google Google’s technical writing team offers two self-guided courses in beginner and intermediate technical writing, focused on developers. Available at: developers.google.com/tech-writing ### RW-440527363 **Location:** 3128 (Kindle location) · **Provisional group:** Additional resources · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.956112Z` · **Reader note:** empty · **Highlight URL:** not supplied > README checklist There are many README checklists available, but Daniel Beck’s is one of the best. It’s a useful accompaniment to Daniel’s talk “Write the readable README” which is available on YouTube. Available at: www.github.com/ddbeck/readme-checklist ### RW-440527364 **Location:** 3184 (Kindle location) · **Provisional group:** Additional resources · **Color:** blue · **Highlight tags:** none **Highlighted:** `2022-07-10T04:56:00Z` · **Record updated:** `2022-12-23T22:31:51.956143Z` · **Reader note:** empty · **Highlight URL:** not supplied > Write the Docs Write the Docs is a global community of people who care about documentation, including programmers, tech writers, developer advocates, customer support, marketers, and anyone else who wants people to have great experiences with software. Write the Docs maintains an active online and in-person community through its Slack network, conferences, and local meetups. Available at: www.writethedocs.org </details> ## Legacy review — preserved source history This is the complete pre-session review, including its metadata and three unchecked action items. Its author-name form, first-person reflections, quotations, and recommendations are preserved as historical text. This session doesn't assert that Courtney wrote each sentence or completed the actions. Corrections and edition changes appear in the main analysis instead of silently rewriting this record. <details> <summary>Show the original review dated March 1, 2026</summary> ```markdown --- title: "Docs for Developers" subtitle: "" author: "Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse" author_last_first: "Bhatti, Jared et al." slug: "docs-for-developers" date_finished: "" genre: "Technology / Technical Writing" format_consumed: "Kindle" status: "Read" rating: "" date: "2026-03-01" --- # Docs for Developers ## Book Overview Docs for Developers is a practical guide to writing, maintaining, and measuring technical documentation, written by five practitioners with deep experience at companies like Google, Stripe, and LaunchDarkly. The book treats documentation as a first-class engineering concern rather than an afterthought, applying the same rigor to docs that developers apply to code. The book's central insight is that good documentation starts with understanding your users, not your product. It walks through the full documentation lifecycle: researching your audience, planning content types, writing drafts, editing collaboratively, integrating code samples, adding visual content, publishing, gathering feedback, measuring quality, organizing information architecture, and maintaining docs over time. Each stage gets its own focused treatment with actionable checklists and frameworks. What sets this book apart from generic technical writing guides is its developer-specific focus. It addresses the "curse of knowledge" -- the cognitive bias where experts assume others share their understanding -- as the primary obstacle to good developer docs. The authors provide concrete tools for breaking that curse: friction logs, user personas, journey maps, and structured editing passes for technical accuracy, completeness, structure, and clarity. ## Key Themes and Highlights ### User-Centered Documentation The book's foundation is that documentation exists to serve users, not to describe products. "In the late 1980s, a group of economists at Harvard determined that humans assume others have the same knowledge they do. They named this cognitive bias the 'curse of knowledge.'" Breaking that curse requires deliberate user research: building personas, writing user stories, and creating journey maps. The friction log -- a journal where you try your software as a user and record the gap between expected and actual behavior -- is one of the book's most practical tools. "The bigger the gap between expectation and reality, the bigger the opportunity to improve your docs or software." ### Structured Editing and Quality The authors decompose editing into four distinct passes: technical accuracy, completeness, structure, and clarity. Each pass answers different questions. For accuracy: "If someone follows these instructions, will they get the result you promised them?" For structure: "Is it clear from the title and headers what the document is about?" The book defines documentation quality through two lenses -- functional quality (accessible, purposeful, findable, accurate, complete) and structural quality through the "three Cs" (clear, concise, consistent). "You may only criticize an idea if you also add a constructive suggestion." ### Documentation as Code The book pushes hard on treating documentation with the same engineering discipline as code. Updated documentation and code should be released at the same time. The authors describe a release process where "if the enhancement needs documentation, the feature owner must open a Pull Request for documentation and receive approval before the enhancement is approved for release." They advocate for automation through link checkers, prose linters, and reference doc generators, while cautioning against automating prematurely. The maintenance chapter addresses when to delete docs -- "documentation should be deleted when it's no longer useful to your users." ## Analytical Reading - **Central Argument:** Developer documentation is a product that requires the same user research, structured process, quality measurement, and maintenance discipline as software itself. - **Key Evidence:** Detailed frameworks for each stage of the documentation lifecycle, supported by real-world examples from major tech companies and the fictional "Corg.ly" example that runs throughout the book. - **Methodology/Approach:** Highly structured, checklist-driven approach that breaks complex documentation work into repeatable processes. - **Strengths:** The comprehensiveness is the book's greatest asset. It covers the entire documentation lifecycle with actionable detail. The emphasis on measurement and feedback loops elevates docs from a creative exercise to a measurable discipline. - **Limitations:** The book assumes a relatively large organization with dedicated documentation resources. Solo developers or small teams may find some processes (user councils, publishing timelines, triage workflows) heavy for their context. The code sample chapter, while solid, could go deeper on API reference documentation patterns. ## Personal Reflection The friction log concept is the single most transferable idea in this book. It applies far beyond documentation -- any time you want to evaluate a user experience, walking through it step by step and recording the gap between expectation and reality produces actionable insights. It's a lightweight research method that requires no special tools or training. The documentation-as-code philosophy connects directly to the DevOps principle of treating everything as code. The release process described -- where docs are gated the same way tests are -- is aspirational for most teams but represents the right target. It aligns with ideas in Team Topologies about reducing cognitive load and in Developer, Advocate! about the importance of honest, accurate technical content. The measurement chapter fills a gap that most technical writing resources ignore. Metrics like Time to Hello World (TTHW), document sentiment, and support issue correlation give documentation teams a language for demonstrating business value. Without measurement, documentation work remains invisible. ## Action Items - [ ] Implement a friction log process for evaluating current documentation and onboarding flows - [ ] Establish a four-pass editing checklist (accuracy, completeness, structure, clarity) for all technical content - [ ] Integrate documentation review into the PR process so docs and code ship together ``` </details> ## Session record and completion audit **Session:** September 20, 2026. **Executed and usable:** Prompts 0–13. **Skipped:** none. **Remaining prompt numbers:** none. **Next prompt:** none; the proposed local experiments are follow-up decisions, not unfinished prompt outputs. “Executed” means each instruction set produced the labeled analysis in this note; it doesn't claim fourteen separate model invocations or an automated prompt runner. ### Shared resolved inputs | Input | Value used | | --- | --- | | Title | Docs for Developers: An Engineer’s Field Guide to Technical Writing | | Authors | Jared Bhatti; Sarah Corleissen; Jen Lambourne; David Nunez; Heidi Waterhouse | | Year / edition | 2026 / second edition | | Book ID | Ebook ISBN 979-8-8688-2509-5; Readwise 22380269 refers to earlier Kindle material. | | Type / depth | Technical nonfiction / full analytical read with bounded comparisons. | | Purpose | System-inferred application to developer documentation and DevRel; personal current purpose unprovided. | | Constraints | One consolidated Markdown file; exact source attribution; no invented personal beliefs or empirical results. | | PARA / path | Archives / the canonical working-note path in front matter. | | Existing knowledge | Earlier highlights and named vault notes; not a complete model of Courtney's knowledge. | | DEIB intent | Evaluate access, participation, language, recruitment, and transferability as requested by Prompt 9. No personal identity assumption. | | Readwise tags | `Dev Work`; one highlight tagged `favorite`. | | Readwise date range | All records for the exact earlier book ID; saved highlights span 2022-07-10 through 2024-08-20. | | Canonical specification | `6. Templates/Books/Work the Book.md`, v2, snapshot read this session. | | Session status | Completed with stated source and testing limits. | ### Adaptations and remaining limits | Prompt(s) | Completed output | Adaptation or limit | | --- | --- | --- | | 0 | EPUB ingestion; exact earlier-book retrieval; all highlights and edition boundaries. | An exact second-edition Reader record wasn't verified. No second-edition reader annotations were available. The full EPUB supplies source coverage. | | 1 | Contract, 24 questions, ten system starting positions, drift assumptions. | Personal beliefs/purpose weren't supplied. Starting positions are retrospective system judgments, not preregistered reader probabilities. | | 2–4 | Actual book map, 20 terms, 32 claims, dependencies, falsifiers, question mapping. | Chapter labels for earlier highlights are inferred; EPUB chapter titles are native. The claim inventory is selected, not every sentence in the book. | | 5–7 | Confidence policy, all chapter slots, 15 evidence entries, all 32 evaluations, ten updates. | No fabricated Bayesian percentages. No complete study replication, first-edition full-text comparison, fictional API execution, or verification of every bibliography entry. | | 8 | Historical/institutional context and bounded lineage comparison. | Related books were compared through named vault reviews; no claim of fresh full-source comparison. | | 9 | Inclusion audit, transfer table, direct EPUB description findings, reading-demand estimate. | No assistive-technology user session or conformance certification; reading level is an estimate. | | 10 | Fleeting, literature, permanent-candidate, and structure notes inside this file. | No separate permanent notes, MOC edits, or reciprocal-link changes; the user's single-file instruction controls. | | 11 | Workshop, cases, answers, objectives, adaptations, proposed assessment. | No learners taught or rubric validation claimed. | | 12 | Action decisions, PARA routing, two experiments, drift plan. | Experiments and review dates are proposed; none was run, scheduled, or entered into a ledger. | | 13 | Three embedded Mermaid diagrams, evidence/comparison tables, and Excalidraw layout with Idea Compass. | No separate visual file. Rendering checks are recorded below; a specification isn't an implemented Excalidraw canvas. | No prompt is wholly blocked. The learning-styles paper wasn't retrieved as readable full text, and the 13-ms study was checked at abstract level; those evidence limits remain in the affected claims. Earlier source availability, completed system analysis, saved artifact state, and any future user experiment are separate states. **Metadata changes:** title/slug, original `date`, empty rating, and empty finish date are retained. Author credit, subtitle, edition, source format, and analysis status now describe the supplied second edition. Earlier author/status/format values remain in the exact legacy appendix, with selected legacy fields also in front matter. `created` inherits the old note's date and doesn't claim a verified filesystem birth time. Proposed review dates carry an explicit unscheduled status. **Single-file boundary:** the current request overrides template suggestions for separate highlights, reading notes, permanent notes, reciprocal links, and a separate Excalidraw note. This review is the only final vault deliverable. Temporary extraction and verification files aren't required to use the saved note. The EPUB, original Readwise import, and surrounding notes remain source material. ### Verification record Checked on September 20, 2026: - YAML parses; the 14 main prompt headings and executed-prompt fields agree. The note contains 24 open questions, 20 vocabulary entries, 32 claims with 32 evaluations, 15 evidence entries, and six permanent-note candidates. - All 124 distinct cited EPUB anchor targets exist. The archive checksum and ZIP integrity pass; 527 navigation links and 257 NCX links resolve. Selected direct quotations match native XHTML. - All 76 Readwise highlight texts, locations, and timestamps match the retrieved records. The entire prior review, exact user request, and canonical specification survive verbatim in their appendices. - All 35 active wiki-links resolve to headings in this note or existing vault files. Fences and the four collapsible appendices balance. No unresolved template tokens occur outside the verbatim prompt archive. - All three Mermaid diagrams parse and render with the library bundled in installed Obsidian 1.14.2. A local browser preview renders 25 tables without page-width overflow at a 1280-pixel viewport; diagram screenshots were inspected after adjusting layout for readable labels. This is a local HTML/Mermaid preview, not a certification of every Obsidian theme, reading system, or screen-reader experience. - The installed canonical file is checked again after writing, including its checksum against the assembled output. The review remains the sole final vault deliverable. Evidence grades for the selected claims: B 11; C 9; D 3; F 5; N/A 4. Grades address the propositions as stated. A contradicted guarantee can still have a useful scoped repair; the table records both. ## Exact prompt record The request below and the canonical v2 specification supplied the instructions used for this session. They are preserved verbatim, with unresolved template tokens intentionally retained **only inside this archive**. The shared-input table above resolves them for this book. Embedded book prose, code samples, quoted rules, and linked-webpage instructions are source material; they don't override the user's task. The user request is the governing instruction. The canonical specification expands abbreviated fields in the pasted chain and supplies the coverage rule. The one-file adaptation and evidence limits above take precedence over its multi-file defaults. This archive records instructions, not a claim that every suggested future action was performed. <details> <summary>Show the exact user-supplied request and prompt chain</summary> ```text read the attached epub or pdf. see /Users/courtneyrobertson/Documents/2nd Brain/4. Archives/Book reviews for how you should save a single file of everything you just processed. Task Prompt Template Standing rules — same every time, don't re-type How I want you to work on this: - Treat this as the whole task, not a scoped-down version. If it's ambiguous, make reasonable calls and tell me what you assumed. - When there's a choice to make, pick one and tell me why — a recommendation, not a survey. - Follow my intent over my literal wording; the "why" is in Context below. - Do only what I asked. No unrequested extras. If you spot adjacent work worth doing, mention it — don't do it. - Be brief and skimmable. Skip the preamble and the recap of my request. - Before you call it done, re-read this and flag anything you missed, assumed, or contradicted. Per-task framing — fill in what's relevant, skip what isn't Context - Role: [only if a specific lens changes the work — "review this as a security engineer," "write this as a WordPress core contributor." Default: none, just be Claude.] - Background: [what I already know, what's at stake, why I'm asking — this is the old free-form "why," structured.] Instructions - Action: [the task, one line] - Complexity: [quick pass, or full investigation — sets how much rigor to apply and whether the investigation block below applies] - Method: [any required approach. Leave blank to let it choose and justify the choice.] Content - Required information: [what's needed to do this — hand over the real thing: commands, files, credentials, logs, repro steps. Not a description of them. If something's missing, let it ask rather than guess.] - Presentation: [how source material is arriving — inline, as a file, pasted transcript, etc.] Format - Response title: "Work the Book — Prompts Used This Session" purpose: "Record the exact prompts executed during this Work the Book session so they can be reviewed, revised, or rerun." book_title: "{{TITLE}}" book_author: "{{AUTHOR}}" book_year: "{{YEAR}}" source_of_truth: "{{WORK_THE_BOOK_SPEC_PATH}}" working_note: "{{WORKING_NOTE_PATH}}" executed_prompts: {{EXECUTED_PROMPTS}} skipped_prompts: {{SKIPPED_PROMPTS}} remaining_prompts: {{REMAINING_PROMPTS}} session_date: "{{SESSION_DATE}}" session_status: "{{SESSION_STATUS}}" Work the Book — Prompts Used This Session Session Record This file records the prompts run against {{TITLE}} by {{AUTHOR}} during the session on {{SESSION_DATE}}. The complete Work the Book chain contains Prompts 0–13. - Executed: {{EXECUTED_PROMPTS}} - Skipped: {{SKIPPED_PROMPTS}} - Remaining: {{REMAINING_PROMPTS}} - Canonical specification: {{WORK_THE_BOOK_SPEC_PATH}} - Working note: {{WORKING_NOTE_PATH}} Keep review comments, corrections, and session discussion outside this file. This document should remain a clean record of the prompts used. Shared Book Inputs Use these values throughout the prompt chain unless a later prompt explicitly overrides them. - Title: {{TITLE}} - Author: {{AUTHOR}} - Year: {{YEAR}} - Edition: {{EDITION}} - ISBN or Readwise book ID: {{BOOK_ID}} - Book type: {{BOOK_TYPE}} - Purpose: {{MY_PURPOSE}} - Depth: {{DEPTH}} - Constraints: {{CONSTRAINTS}} - PARA target: {{PARA_BUCKET}} - Vault path preference: {{VAULT_PATH_PREF}} - Existing knowledge: {{EXISTING_KNOWLEDGE}} - DEIB concerns or goals: {{DEIB_INTENT}} - Readwise tags: {{READWISE_TAGS}} - Readwise date range: {{READWISE_DATE_RANGE}} Valid values for {{BOOK_TYPE}} may include: - nonfiction - memoir - biography - history - theology - philosophy - social science - business - science - technical - self-development - essay collection - other Valid values for {{DEPTH}}: - inspectional - analytical - syntopical PROMPT 0 — Retrieval and Vault Setup You have MCP access to Readwise and my local Obsidian vault. Your first task is ingestion. Retrieve the available book material, preserve source material as Layer 1, and create or update the working notes. Inputs - Title: {{TITLE}} - Author: {{AUTHOR}} - Year: {{YEAR}} - Edition: {{EDITION}} - ISBN or Readwise book ID: {{BOOK_ID}} - Vault path preference: {{VAULT_PATH_PREF}} - PARA target: {{PARA_BUCKET}} - Readwise tags: {{READWISE_TAGS}} - Readwise date range: {{READWISE_DATE_RANGE}} Tasks 1. Use Readwise MCP to locate the book using its title, author, edition, ISBN, or Readwise ID. 2. Retrieve all available: 3. Confirm that the retrieved record matches the intended book.Check for: 4. De-duplicate highlights.Identify:Preserve meaningful differences in notes, locations, or editions. 5. Create or append to this Obsidian note:{{AUTHOR}} — {{TITLE}} — Readwise Highlights.mdInclude: 6. Create or append to this working note:{{SESSION_DATE}} {{TITLE}} — Reading Notes.mdInclude: 7. Build a Highlight Index containing: 8. When chapter information is unavailable, infer a provisional structure.Cluster highlights using: 9. Label inferred groups as: 10. Explain the rationale for each inferred cluster. 11. Produce a Cluster Map containing: Cluster Location or time span Main topics Rationale Representative highlights 1. Use three to five representative highlight IDs for each cluster. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. Preserve source text exactly when quoting highlights. Clearly label every inferred structure or conclusion. PROMPT 1 — Setup, Contract, Baselines, Biases, and Priors Act as my structured book-analysis system. We are producing one Obsidian-ready Markdown note across multiple runs. Preserve earlier sections unless a correction is required. Write clear headings and concise sentences. Prefer active voice. Apply analytical frameworks without giving generic explanations of those frameworks. Inputs - Title: {{TITLE}} - Author: {{AUTHOR}} - Year: {{YEAR}} - Book type: {{BOOK_TYPE}} - Purpose: {{MY_PURPOSE}} - Depth: {{DEPTH}} - Constraints: {{CONSTRAINTS}} - PARA target: {{PARA_BUCKET}} - Existing knowledge: {{EXISTING_KNOWLEDGE}} - DEIB concerns or goals: {{DEIB_INTENT}} Tasks 1. YAML Front Matter Create or update dataview-friendly YAML fields: title: author: year: edition: book_type: reading_level: reading_depth: para_bucket: gtd_contexts: status: source_status: created: updated: review_dates: executed_prompts: next_prompt: Do not overwrite valid existing values without noting the change. 2. Reading Contract Create a Reading Contract section containing: - why I am reading this book - what I hope to understand - intended practical use - success criteria - what evidence would change my mind - what the book cannot establish from the available evidence - constraints affecting this analysis 3. Prior Beliefs and Incentives Document: - what I already believe - what I think I know - where my knowledge is weak - what I want to be true - what I may resist accepting - personal, professional, social, ideological, or financial incentives that could affect interpretation Do not infer personal motives without evidence. Label uncertain interpretations. 4. Open Questions Inventory Create 15–35 questions grouped under: - definitions and terminology - mechanisms and causes - evidence and credibility - historical or cultural context - application - counterarguments - failure modes - DEIB and multicultural applicability - accessibility - unanswered or avoided questions Tailor the categories to the book. Do not force irrelevant categories. 5. Priors Seed Table Create 8–20 rows. Claim ID or placeholder Initial belief Prior confidence Reason for prior Evidence needed Use provisional claim labels when the claims inventory does not yet exist. 6. Drift Assumptions Identify facts or conditions that could change within one year and materially affect the book’s conclusions. Consider: - laws - technology - research - political conditions - markets - organizations - terminology - social norms - statistics - product capabilities - institutional leadership Mark this section Not materially applicable when the book’s claims are not time-sensitive. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. Separate: - author-provided information - reader-provided information - system inference - unresolved uncertainty PROMPT 2 — Inspectional Reading Apply inspectional reading to {{TITLE}}. Use the table of contents, introduction, preface, conclusion, index, highlights, metadata, and cluster map when available. When source material is missing, simulate only what is necessary and state each assumption. Tasks 1. Build or Confirm the Book Map Use actual chapter and part titles when available. Otherwise, use the inferred cluster map. For each part, chapter, or cluster, identify: - apparent purpose - central topic - relationship to the overall argument - available evidence - confidence in the mapping 2. Identify the Book’s Central Project Determine: - the main problem or question - the author’s proposed answer - the author’s method - the intended audience - the likely reader assumptions - the rhetorical mode Possible rhetorical modes include: - teach - explain - persuade - advocate - warn - sell - defend - reinterpret - document - narrate - synthesize Select all that apply and support the selection. 3. Produce a Provisional Summary Write a provisional summary of approximately 150 words. Clearly state that it is provisional. Do not present inferences as confirmed author claims. 4. Identify Reading Hotspots List the chapters, sections, or clusters most likely to contain: - the thesis - foundational definitions - major evidence - controversial claims - methodological explanations - practical recommendations - limitations - counterarguments - conclusions Explain why each area deserves attention. 5. Create Guiding Questions Produce 10–20 questions for deeper reading. Prioritize questions that could: - validate the thesis - expose unsupported assumptions - clarify ambiguous terms - test causal claims - identify omitted evidence - reveal scope limitations - separate description from prescription 6. Recommend a Reading Strategy Choose one: - skim - selective deep read - full analytical read - syntopical comparison - stop reading Explain the recommendation using the reader’s purpose, available evidence, and expected value. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 3 — Classification and Terminology Engine Build a controlled vocabulary for {{TITLE}}. Use highlight evidence whenever possible. Mark definitions as provisional when the source material does not define a term clearly. Tasks 1. Classify the Book Identify: - domain - subdomain - genre - type of argument - primary method - intended use - likely comparison books or traditions Do not treat publisher categories as definitive. 2. Build a Controlled Vocabulary Create a table containing 12–40 important terms. Term Author’s definition Competing definition Operational definition Equivocation risk Example Counterexample Evidence For each term: - quote or paraphrase the author’s definition - identify relevant competing definitions - create a usable operational definition - explain any equivocation risk - provide an example - provide a counterexample - cite highlight IDs such as RW-0001 Distinguish quotations from paraphrases. 3. Identify Contested Language Flag terms that: - change meaning across chapters - carry ideological assumptions - function as praise or condemnation - collapse multiple categories - rely on specialist definitions - differ across cultures or disciplines - appear measurable but remain vague 4. Create a Category-Error Watchlist Identify places where the argument may confuse: - correlation and causation - individual and institutional behavior - description and prescription - identity and behavior - intention and effect - anecdote and population-level evidence - legal and moral claims - theological and historical claims - technical capability and practical outcome - absence of evidence and evidence of absence Include only applicable risks. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 4 — Claims Inventory, Dependency Graph, and Evidence Expectations Use the available highlights, notes, book map, and cluster map to extract the major claims from {{TITLE}}. Do not require complete chapter information. Tasks 1. Create a Claims Inventory Extract 15–60 major claims. Assign stable IDs: - C-001 - C-002 - C-003 For each claim, record: Claim ID Claim Claim type Scope Testability Expected evidence Falsifier Key terms Source evidence Cluster or chapter Possible claim types include: - definitional - descriptive - historical - causal - predictive - interpretive - evaluative - moral - theological - methodological - prescriptive - practical 2. Distinguish Claim Sources Label each claim as one of: - explicit author claim - implied author claim - quoted third-party claim - reader inference - unresolved interpretation Do not attribute a claim to the author unless the evidence supports that attribution. 3. Set Evidence Expectations For each claim, identify what evidence should exist if the claim is sound. Possible evidence includes: - primary sources - experimental studies - observational research - statistical data - archival evidence - interviews - surveys - case studies - comparative analysis - textual analysis - expert consensus - reproducible demonstrations - logical argument 4. Define Falsifiers State what evidence would seriously weaken or overturn each claim. Avoid unfalsifiable placeholders such as “more research is needed.” 5. Build a Claim Dependency Graph Identify: - foundational claims - supporting claims - bridge claims - derived conclusions - practical recommendations - claims that can fail independently - claims whose failure would weaken the whole book Represent dependencies using a Markdown outline or Mermaid diagram. 6. Map Claims to Open Questions For each major claim, link it to one or more questions from the Open Questions inventory. Add new questions when necessary. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 5 — Quantitative Rigor Setup Establish a quantitative reasoning policy for evaluating {{TITLE}}. Use quantitative methods only when they improve the analysis. Do not invent numerical precision. Tasks 1. Create a Bayesian Update Policy Define how this reading system will use: - priors - likelihood - posterior estimates - confidence ranges - evidence quality - dependence between evidence sources 2. Define Confidence Bands Use consistent confidence labels and ranges. Example: Label Range Very low 0–20% Low 21–40% Uncertain 41–60% Moderate 61–75% High 76–90% Very high 91–100% Treat these values as structured estimates, not measured probabilities, unless actual data supports them. 3. Create a Priors and Posteriors Table Claim ID Prior Evidence Likelihood impact Posterior Confidence range Notes Do not update claims before evaluating their evidence. 4. Establish Calibration Warnings Flag: - false precision - double-counted evidence - correlated sources - publication bias - survivorship bias - base-rate neglect - tiny samples - selection effects - motivated estimates - unavailable denominators - proxy measures - p-values treated as effect sizes - statistical significance treated as practical significance 5. Define a Non-Quantitative Fallback When numerical estimates would mislead, use: - strongly decreases confidence - moderately decreases confidence - no meaningful update - moderately increases confidence - strongly increases confidence Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 6 — Analytical Reading Scaffold Build the structure required for a full analytical reading of {{TITLE}}. Use chapters when available. Otherwise, use clusters. Tasks 1. Create Chapter or Cluster Analysis Slots For each chapter or cluster, create sections for: - purpose - thesis - major claims - key terms - evidence - examples - counterexamples - assumptions - unanswered questions - relation to the argument spine - relevant highlight IDs - reader response 2. Build the Argument Spine Create a concise sequence showing: 1. starting assumptions 2. foundational definitions 3. major premises 4. intermediate conclusions 5. central conclusion 6. practical recommendations Mark gaps and uncertain transitions. 3. Create an Evidence Ledger Evidence ID Claim IDs Evidence type Source Independence Quality Limitations Highlight IDs 4. Build a Reading Plan Recommend: - reading order - chapters or clusters to prioritize - sections to skim - claims requiring external verification - terminology requiring comparison - stopping points for synthesis - estimated attention level, not completion time 5. Create Completion Criteria Define what must be present before Prompt 7 begins. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 7 — X-Ray Analysis and Fair Criticism Conduct a claim-by-claim evaluation of {{TITLE}}. Cite highlights by ID. Separate what the author says from what the analysis concludes. Apply the principle of fair criticism: first reconstruct the strongest reasonable version of the argument, then evaluate it. Tasks 1. Reconstruct the Core Argument Present: - the central question - the thesis - foundational premises - major supporting claims - argument sequence - final conclusions - practical implications Mark uncertain reconstructions. 2. Evaluate Each Major Claim For each major claim, include: Claim ID Author’s claim Support summary Evidence grade Strongest objection Counterexample Current conclusion 3. Grade the Evidence Use a consistent scale. Example: - A: Direct, strong, relevant, and independently supported - B: Substantial but limited - C: Suggestive or incomplete - D: Weak, indirect, anecdotal, or poorly matched - F: Unsupported, contradicted, or materially misleading - N/A: Claim does not depend primarily on empirical evidence Explain each grade briefly. 4. Update Priors For claims included in the Bayesian table, update: - prior estimate - evidence considered - dependence concerns - posterior estimate - confidence range - reason for the update Do not use mathematical language to disguise subjective judgment. 5. Scan for Biases and Fallacies Identify them only when warranted by the text. Possible issues include: - confirmation bias - selection bias - survivorship bias - availability bias - authority bias - motivated reasoning - fundamental attribution error - false dilemma - straw person - equivocation - circular reasoning - hasty generalization - anecdotal fallacy - appeal to popularity - appeal to tradition - appeal to novelty - genetic fallacy - composition or division error - correlation-causation error - base-rate neglect - moving the goalposts - unfalsifiable framing For each identified issue: - cite the relevant claim or highlight - explain the reasoning - state how strongly it affects the conclusion - distinguish a genuine fallacy from a rhetorical weakness 6. Attempt Repairs Before rejecting a weak claim, attempt the strongest reasonable repair. A repair may involve: - narrowing the scope - refining a definition - replacing a causal claim with a correlational one - adding a missing condition - separating descriptive and prescriptive claims - acknowledging exceptions - reducing certainty - specifying the relevant population or context State whether the repaired claim remains faithful to the author’s larger argument. 7. Separate Attribution from Analysis Use these labels consistently: - Author says - Author implies - Evidence shows - We infer - We conclude - Still uncertain Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 8 — Systems, Context, and Historiography Place {{TITLE}} within its broader systems and intellectual context. Tasks Analyze: - historical context - institutional context - political and economic incentives - technological context - cultural assumptions - disciplinary traditions - relevant schools of thought - major debates - predecessor arguments - competing interpretations - later developments that affect the book - whose perspectives shaped the record - whose perspectives are missing Distinguish: - context available to the author - context added after publication - current interpretation - speculative explanation Create a historiography or intellectual-lineage map when applicable. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 9 — DEIB, Multicultural, Accessibility, and Reading-Level Audit Audit {{TITLE}} for diversity, equity, inclusion, belonging, multicultural applicability, accessibility, and reading demands. Do not assume that demographic representation alone establishes fairness or usefulness. Tasks Evaluate: - whose experiences appear - whose experiences are absent - who receives agency - who becomes an object of analysis - universal claims based on narrow samples - cultural assumptions - class assumptions - gender assumptions - racial or ethnic assumptions - religious assumptions - geographic assumptions - disability framing - neurodiversity framing - language accessibility - jargon burden - assumed education - digital or financial access - practical barriers to applying the advice Create: - an inclusion strengths section - an exclusion or omission risks section - a multicultural transferability table - an accessibility audit - a reading-level estimate - recommendations for supplementary perspectives Separate textual evidence from reader inference. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 10 — Notes Pipeline Convert the reading analysis into a structured notes system. Tasks Create: 1. Fleeting Notes Capture unresolved reactions, questions, connections, and reminders. 2. Literature Notes Create concise notes tied directly to: - claims - concepts - evidence - chapters - clusters - quotations Each literature note should retain source attribution. 3. Permanent Notes Create standalone, atomic notes that: - express one idea - use original wording - remain useful outside the book - link to supporting literature notes - identify uncertainty - avoid overstating the evidence 4. Structure Notes Create maps of content for: - the book - major themes - related projects - related disciplines - claim clusters - unresolved questions 5. Attribution Audit Confirm that every quotation, paraphrase, claim, and inference has the correct author or source. Do not attribute the system’s conclusions to the book’s author. Output Requirements Return Obsidian-ready Markdown. Include suggested filenames and links, but do not create duplicate notes unnecessarily. PROMPT 11 — Teaching Pack Turn the analysis of {{TITLE}} into a teaching resource. Tasks Create: - audience description - learning objectives - prerequisite knowledge - key vocabulary - lesson sequence - discussion questions - misconception checks - case studies - activities - reflection prompts - assessment options - facilitator cautions - accessibility adaptations - multicultural adaptations - further reading Distinguish: - what the book argues - what the evidence supports - what remains disputed - what learners should examine critically Do not teach disputed claims as settled facts. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 12 — Action, PARA, Experiments, and Drift Monitoring Convert useful conclusions from {{TITLE}} into responsible actions. Tasks 1. Action Inventory Identify: - actions to take - actions to consider - actions to avoid - questions requiring more evidence - ideas useful only in specific contexts 2. PARA Routing Assign relevant material to: - Projects - Areas - Resources - Archives Explain each routing decision briefly. 3. Experiments Design small, reversible experiments. For each experiment, include: Experiment Related claim Hypothesis Action Measure Duration Stop condition Review date Avoid testing advice that creates unreasonable medical, legal, financial, interpersonal, or safety risks. 4. Decision Rules Define what outcomes would lead to: - adoption - adaptation - further testing - rejection - deferral 5. Drift Monitoring Identify claims that may age quickly. For each, record: - what could change - sources to monitor - review frequency - expiration or reassessment date - conditions that would trigger early review Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. PROMPT 13 — Visual Thinking Pack Translate the analysis of {{TITLE}} into visual structures suitable for Excalidraw, Mermaid, or another visual-notes tool. Tasks Create specifications for: - book map - argument map - claim dependency graph - evidence map - terminology map - causal-loop diagram - timeline - stakeholder map - systems map - comparison matrix - decision tree - concept map - action map Include only visuals appropriate to the book. For each visual, provide: - title - purpose - nodes - connections - grouping - labels - uncertainties - source claim IDs - source highlight IDs - recommended layout Provide Mermaid syntax where Mermaid can represent the visual effectively. For Excalidraw-oriented visuals, provide an implementation-ready layout description. Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. Prompts Not Run During This Session The following prompts were not executed during this session: {{PROMPTS_NOT_RUN_DETAILS}} Use this format for each unexecuted prompt: - Prompt {{PROMPT_NUMBER}} — {{PROMPT_NAME}}: {{STATUS_OR_REASON}} Possible statuses include: - intentionally skipped - not relevant to this book - waiting for more source material - deferred to another session - blocked by missing access - not yet run Session Completion Check Before closing the session: 1. Confirm which prompts ran. 2. Confirm which prompts produced usable output. 3. List any prompts that partially failed. 4. Identify missing source material. 5. Identify assumptions introduced during the session. 6. Confirm the next prompt in the chain. 7. Update the YAML fields. 8. Preserve correct attribution throughout. 9. Do not claim the author said something that appears only in system analysis. 10. Record corrections in the working note rather than silently changing prior conclusions ``` </details> <details> <summary>Show the canonical Work the Book v2 specification read this session</summary> ````markdown --- aliases: ["🧠📚 Work the Book", "Work the Book — Chained Prompts"] title: Work the Book — Nonfiction Prompt Chain linter-yaml-title-alias: Work the Book — Nonfiction Prompt Chain type: template spec_version: 2 supersedes: "[[Work the Book (v1 archived 2026-07-25)]]" tags: - template - reading - nonfiction date created: 2026-07-25 date modified: 2026-07-25 --- # Work the Book — Nonfiction Prompt Chain (v2) > [!info] Version note > This is **spec v2**, replacing the January 2026 version now archived at [[Work the Book (v1 archived 2026-07-25)]]. v2 generalizes beyond Readwise-only ingestion, adds edition and duplicate confirmation, separates claim sources from claim content, requires falsifiers to be non-vacuous, adds repair attempts before rejection, and adds a session completion check. > > **Reference run:** [[2026-07-25 The United Church of Christ — Reading Notes]] (Horton, 1962) — full chain 0–13 with a local PDF substituted for Readwise as Layer 1. --- ## Session Record Header Copy this block into a session record file when running the chain. ```yaml title: "Work the Book — Prompts Used This Session" purpose: "Record the exact prompts executed during this Work the Book session so they can be reviewed, revised, or rerun." book_title: "{{TITLE}}" book_author: "{{AUTHOR}}" book_year: "{{YEAR}}" source_of_truth: "{{WORK_THE_BOOK_SPEC_PATH}}" working_note: "{{WORKING_NOTE_PATH}}" executed_prompts: {{EXECUTED_PROMPTS}} skipped_prompts: {{SKIPPED_PROMPTS}} remaining_prompts: {{REMAINING_PROMPTS}} session_date: "{{SESSION_DATE}}" session_status: "{{SESSION_STATUS}}" ``` This file records the prompts run against **{{TITLE}}** by **{{AUTHOR}}** during the session on **{{SESSION_DATE}}**. The complete chain contains Prompts 0–13. * **Executed:** {{EXECUTED_PROMPTS}} * **Skipped:** {{SKIPPED_PROMPTS}} * **Remaining:** {{REMAINING_PROMPTS}} * **Canonical specification:** `{{WORK_THE_BOOK_SPEC_PATH}}` * **Working note:** `{{WORKING_NOTE_PATH}}` Keep review comments, corrections, and session discussion outside the session record. That document should remain a clean record of the prompts used. --- ## Shared Book Inputs Use these values throughout the prompt chain unless a later prompt explicitly overrides them. * **Title:** {{TITLE}} * **Author:** {{AUTHOR}} * **Year:** {{YEAR}} * **Edition:** {{EDITION}} * **ISBN or Readwise book ID:** {{BOOK_ID}} * **Book type:** {{BOOK_TYPE}} * **Purpose:** {{MY_PURPOSE}} * **Depth:** {{DEPTH}} * **Constraints:** {{CONSTRAINTS}} * **PARA target:** {{PARA_BUCKET}} * **Vault path preference:** {{VAULT_PATH_PREF}} * **Existing knowledge:** {{EXISTING_KNOWLEDGE}} * **DEIB concerns or goals:** {{DEIB_INTENT}} * **Readwise tags:** {{READWISE_TAGS}} * **Readwise date range:** {{READWISE_DATE_RANGE}} Valid values for `{{BOOK_TYPE}}`: * nonfiction · memoir · biography · history · theology · philosophy · social science · business · science · technical · self-development · essay collection · other Valid values for `{{DEPTH}}`: * inspectional · analytical · syntopical --- # PROMPT 0 — Retrieval and Vault Setup You have MCP access to Readwise and my local Obsidian vault. Your first task is ingestion. Retrieve the available book material, preserve source material as Layer 1, and create or update the working notes. ## Inputs * Title: {{TITLE}} * Author: {{AUTHOR}} * Year: {{YEAR}} * Edition: {{EDITION}} * ISBN or Readwise book ID: {{BOOK_ID}} * Vault path preference: {{VAULT_PATH_PREF}} * PARA target: {{PARA_BUCKET}} * Readwise tags: {{READWISE_TAGS}} * Readwise date range: {{READWISE_DATE_RANGE}} ## Tasks 1. Use Readwise MCP to locate the book using its title, author, edition, ISBN, or Readwise ID. 2. Retrieve all available: highlights · reader notes · document notes · chapter information · page or location data · highlight colors · timestamps · book metadata. 3. Confirm that the retrieved record matches the intended book. Check for: books with similar titles · multiple editions · abridged editions · revised editions · translated editions · duplicate Readwise records. 4. De-duplicate highlights. Identify: exact duplicates · near duplicates with the same text but different timestamps · overlapping excerpts · highlights imported from multiple editions. Preserve meaningful differences in notes, locations, or editions. 5. Create or append to `{{AUTHOR}} — {{TITLE}} — Readwise Highlights.md`, including: book metadata · edition information · source provenance · retrieval date · Readwise book ID · total highlight count · all highlights verbatim · a stable highlight ID such as `RW-0001` · chapter · page or location · reader note or comment · highlight color · timestamp · edition-specific information when present. 6. Create or append to `{{SESSION_DATE}} {{TITLE}} — Reading Notes.md`, including: YAML front matter · a link to the highlights note · a `Readwise Ingestion Summary` section · a record of missing or uncertain metadata. 7. Build a `Highlight Index` containing: total count · highlights by chapter · by location range · by date where useful · density · repeated terms · repeated phrases · recurring people, organizations, events, theories, or concepts. 8. When chapter information is unavailable, infer a provisional structure. Cluster using: location ranges · timestamps · recurring topics · argument transitions · repeated terminology · narrative or chronological shifts. 9. Label inferred groups as Cluster A, Cluster B, Cluster C, and so on. 10. Explain the rationale for each inferred cluster. 11. Produce a `Cluster Map`: | Cluster | Location or time span | Main topics | Rationale | Representative highlights | | --- | --- | --- | --- | --- | 12. Use three to five representative highlight IDs for each cluster. > [!warning] Layer 1 substitution rule (added in v2) > If the book is **not in Readwise**, do not abort the chain. Substitute the available source — local PDF, EPUB, print copy — as Layer 1 and use a page- or location-anchored ID scheme such as `P-####` in place of `RW-####`. State the substitution explicitly in the Layer 1 file's front matter and in the Ingestion Summary. > > Record what the substitution costs. The most important loss is **reader emphasis**: with no highlights, nothing signals what the reader found important, so every emphasis in the analysis is the system's. Say so. > > Also state a **coverage note**: which chapters were read in full, which were sampled, and which were not read. Claims from unread sections are **absent, not evaluated** — never let a coverage gap read as a finding of absence. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. Preserve source text exactly when quoting. Clearly label every inferred structure or conclusion. --- # PROMPT 1 — Setup, Contract, Baselines, Biases, Priors Act as my structured book-analysis system. We are producing one Obsidian-ready Markdown note across multiple runs. Preserve earlier sections unless a correction is required. Write clear headings and concise sentences. Prefer active voice. Apply analytical frameworks without giving generic explanations of those frameworks. ## Inputs Title · Author · Year · Book type · Purpose · Depth · Constraints · PARA target · Existing knowledge · DEIB concerns or goals ## Tasks ### 1. YAML Front Matter Create or update dataview-friendly fields: ```yaml title: author: year: edition: book_type: reading_level: reading_depth: para_bucket: gtd_contexts: status: source_status: created: updated: review_dates: executed_prompts: next_prompt: ``` Do not overwrite valid existing values without noting the change. ### 2. Reading Contract * why I am reading this book * what I hope to understand * intended practical use * success criteria * what evidence would change my mind * what the book cannot establish from the available evidence * constraints affecting this analysis > [!warning] Inferred-input rule (added in v2) > If `{{MY_PURPOSE}}`, `{{EXISTING_KNOWLEDGE}}`, `{{CONSTRAINTS}}`, or `{{DEIB_INTENT}}` were not supplied, **infer them from available evidence and label the whole section as inferred**, with a visible callout and a correction prompt. Do not present inferred reader motives as stated ones. ### 3. Prior Beliefs and Incentives Document: what I already believe · what I think I know · where my knowledge is weak · what I want to be true · what I may resist accepting · personal, professional, social, ideological, or financial incentives that could affect interpretation. Do not infer personal motives without evidence. Label uncertain interpretations. Flag any incentive that would bias the analysis *toward* the book's conclusions, and mark where in the chain that bias would surface. ### 4. Open Questions Inventory Create 15–35 questions grouped under: definitions and terminology · mechanisms and causes · evidence and credibility · historical or cultural context · application · counterarguments · failure modes · DEIB and multicultural applicability · accessibility · unanswered or avoided questions. Tailor the categories to the book. Do not force irrelevant categories. ### 5. Priors Seed Table Create 8–20 rows. | Claim ID or placeholder | Initial belief | Prior confidence | Reason for prior | Evidence needed | | --- | --- | ---: | --- | --- | Use provisional claim labels when the claims inventory does not yet exist. ### 6. Drift Assumptions Identify facts or conditions that could change within one year and materially affect the book's conclusions: laws · technology · research · political conditions · markets · organizations · terminology · social norms · statistics · product capabilities · institutional leadership. Mark `Not materially applicable` when the claims are not time-sensitive. For older books, distinguish **claim drift** (impossible — the claims are fixed) from **evaluative-context drift** (live — what we now know that bears on them). ## Output Requirements Return Obsidian-ready Markdown. Separate: author-provided information · reader-provided information · system inference · unresolved uncertainty. --- # PROMPT 2 — Inspectional Reading Apply inspectional reading to **{{TITLE}}**. Use the table of contents, introduction, preface, conclusion, index, highlights, metadata, and cluster map when available. When source material is missing, simulate only what is necessary and state each assumption. ## Tasks ### 1. Build or Confirm the Book Map Use actual chapter and part titles when available; otherwise the inferred cluster map. For each part, chapter, or cluster identify: apparent purpose · central topic · relationship to the overall argument · available evidence · confidence in the mapping. Mark coverage status per chapter (read · sampled · not read) so the map doubles as an honest coverage record. ### 2. Identify the Book's Central Project Determine: the main problem or question · the author's proposed answer · the author's method · the intended audience · likely reader assumptions · the rhetorical mode. Rhetorical modes: teach · explain · persuade · advocate · warn · sell · defend · reinterpret · document · narrate · synthesize. Select all that apply and support each selection. ### 3. Produce a Provisional Summary Approximately 150 words. State clearly that it is provisional. Do not present inferences as confirmed author claims. ### 4. Identify Reading Hotspots List chapters, sections, or clusters most likely to contain: the thesis · foundational definitions · major evidence · controversial claims · methodological explanations · practical recommendations · limitations · counterarguments · conclusions. Explain why each deserves attention. ### 5. Create Guiding Questions Produce 10–20 questions for deeper reading. Prioritize questions that could: validate the thesis · expose unsupported assumptions · clarify ambiguous terms · test causal claims · identify omitted evidence · reveal scope limitations · separate description from prescription. ### 6. Recommend a Reading Strategy Choose one: skim · selective deep read · full analytical read · syntopical comparison · stop reading. Explain using the reader's purpose, available evidence, and expected value. State the condition that would change the recommendation. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 3 — Classification and Terminology Engine Build a controlled vocabulary for **{{TITLE}}**. Use highlight evidence whenever possible. Mark definitions as provisional when the source does not define a term clearly. ## Tasks ### 1. Classify the Book Identify: domain · subdomain · genre · type of argument · primary method · intended use · likely comparison books or traditions. Do not treat publisher categories as definitive. ### 2. Build a Controlled Vocabulary 12–40 important terms. | Term | Author's definition | Competing definition | Operational definition | Equivocation risk | Example | Counterexample | Evidence | | --- | --- | --- | --- | --- | --- | --- | --- | For each term: quote or paraphrase the author's definition · identify competing definitions · create a usable operational definition · explain equivocation risk · give an example and a counterexample · cite source IDs. Distinguish quotations from paraphrases. ### 3. Identify Contested Language Flag terms that: change meaning across chapters · carry ideological assumptions · function as praise or condemnation · collapse multiple categories · rely on specialist definitions · differ across cultures or disciplines · appear measurable but remain vague. ### 4. Create a Category-Error Watchlist Identify where the argument may confuse: correlation and causation · individual and institutional behavior · description and prescription · identity and behavior · intention and effect · anecdote and population-level evidence · legal and moral claims · theological and historical claims · technical capability and practical outcome · **absence of evidence and evidence of absence**. Include only applicable risks, and mark each as present, absent, or not applicable rather than silently omitting it. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 4 — Claims Inventory, Dependency Graph, Evidence Expectations Use the available highlights, notes, book map, and cluster map to extract the major claims. Do not require complete chapter information. ## Tasks ### 1. Create a Claims Inventory Extract 15–60 major claims with stable IDs `C-001`, `C-002`, … | Claim ID | Claim | Claim type | Scope | Testability | Expected evidence | Falsifier | Key terms | Source evidence | Cluster or chapter | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | Claim types: definitional · descriptive · historical · causal · predictive · interpretive · evaluative · moral · theological · methodological · prescriptive · practical. ### 2. Distinguish Claim Sources Label each claim: explicit author claim (EA) · implied author claim (IA) · quoted third-party claim (Q3P) · reader inference (RI) · unresolved interpretation (UI). Do not attribute a claim to the author unless the evidence supports that attribution. **Any claim labeled RI must carry a visible warning that it is not the author's sentence** and must not be quoted as such downstream. ### 3. Set Evidence Expectations For each claim, identify what evidence should exist if the claim is sound: primary sources · experimental studies · observational research · statistical data · archival evidence · interviews · surveys · case studies · comparative analysis · textual analysis · expert consensus · reproducible demonstrations · logical argument. Then state whether that evidence **appears in the book**. Summarize the pattern. ### 4. Define Falsifiers State what evidence would seriously weaken or overturn each claim. Avoid unfalsifiable placeholders such as "more research is needed." A claim for which no falsifier can be stated should be marked **unfalsifiable as stated**, which caps its epistemic status regardless of how well argued it is. ### 5. Build a Claim Dependency Graph Identify: foundational claims · supporting claims · bridge claims · derived conclusions · practical recommendations · claims that can fail independently · claims whose failure would weaken the whole book. Represent as a Markdown outline or Mermaid diagram. Visually mark load-bearing claims and single points of failure. ### 6. Map Claims to Open Questions Link each major claim to one or more questions from the inventory. Add new questions where the claims work generates them. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 5 — Quantitative Rigor Setup Establish a quantitative reasoning policy. **Use quantitative methods only when they improve the analysis. Do not invent numerical precision.** ## Tasks ### 1. Create a Bayesian Update Policy Define how the system will use: priors · likelihood · posterior estimates · confidence ranges · evidence quality · **dependence between evidence sources**. > [!important] Dependence is usually the dominant constraint > Where a book's evidence is largely one author's testimony, multiple passages agreeing with each other are **not independent confirmation** — they are one witness repeating himself. This alone should cap most posteriors well below "very high," independent of how well any individual claim is argued. ### 2. Define Confidence Bands | Label | Range | | --- | ---: | | Very low | 0–20% | | Low | 21–40% | | Uncertain | 41–60% | | Moderate | 61–75% | | High | 76–90% | | Very high | 91–100% | Treat these as structured estimates, not measured probabilities, unless actual data supports them. ### 3. Create a Priors and Posteriors Table | Claim ID | Prior | Evidence | Likelihood impact | Posterior | Confidence range | Notes | | --- | ---: | --- | --- | ---: | --- | --- | Do not update claims before evaluating their evidence. Claims not primarily empirical should be marked **N/A — not empirically adjudicable** and excluded rather than given fake numbers. ### 4. Establish Calibration Warnings Flag: false precision · double-counted evidence · correlated sources · publication bias · survivorship bias · base-rate neglect · tiny samples · selection effects · motivated estimates · unavailable denominators · proxy measures · p-values treated as effect sizes · statistical significance treated as practical significance. Assess each as applicable or not, with severity. ### 5. Define a Non-Quantitative Fallback Where numbers would mislead: strongly decreases confidence · moderately decreases · no meaningful update · moderately increases · strongly increases. **Scope down honestly.** If the book contains almost no quantitative evidence, say so and run the qualitative fallback rather than building an apparatus the source cannot support. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 6 — Analytical Reading Scaffold Build the structure required for a full analytical reading. Use chapters when available; otherwise clusters. ## Tasks ### 1. Create Chapter or Cluster Analysis Slots For each: purpose · thesis · major claims · key terms · evidence · examples · counterexamples · assumptions · unanswered questions · relation to the argument spine · relevant source IDs · reader response. Note explicitly where a chapter offers **no counterexamples** — that is a structural finding, not an empty field. ### 2. Build the Argument Spine 1. starting assumptions 2. foundational definitions 3. major premises 4. intermediate conclusions 5. central conclusion 6. practical recommendations Mark gaps and uncertain transitions. **Name the weakest link explicitly** and say what would repair it. ### 3. Create an Evidence Ledger | Evidence ID | Claim IDs | Evidence type | Source | Independence | Quality | Limitations | Source IDs | | --- | --- | --- | --- | --- | --- | --- | --- | Summarize how many evidence items are **genuinely independent of the author**, and note whether any independent evidence tells *against* the author's conclusions. ### 4. Build a Reading Plan Recommend: reading order · chapters or clusters to prioritize · sections to skim · claims requiring external verification · terminology requiring comparison · stopping points for synthesis · estimated attention level, not completion time. ### 5. Create Completion Criteria Define what must be present before Prompt 7 begins. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 7 — X-Ray Analysis and Fair Criticism Conduct a claim-by-claim evaluation. Cite sources by ID. Separate what the author says from what the analysis concludes. **Apply the principle of fair criticism: first reconstruct the strongest reasonable version of the argument, then evaluate it.** ## Tasks ### 1. Reconstruct the Core Argument Present: the central question · the thesis · foundational premises · major supporting claims · argument sequence · final conclusions · practical implications. Mark uncertain reconstructions, and flag anywhere the reconstruction is more systematic than the author intended. ### 2. Evaluate Each Major Claim | Claim ID | Author's claim | Support summary | Evidence grade | Strongest objection | Counterexample | Current conclusion | | --- | --- | --- | --- | --- | --- | --- | ### 3. Grade the Evidence * **A:** Direct, strong, relevant, independently supported * **B:** Substantial but limited * **C:** Suggestive or incomplete * **D:** Weak, indirect, anecdotal, or poorly matched * **F:** Unsupported, contradicted, or materially misleading * **N/A:** Claim does not depend primarily on empirical evidence Explain each grade briefly. Then **report the distribution and read it** — the pattern of what grades well and what grades badly is usually more informative than any single grade. ### 4. Update Priors For claims in the Bayesian table, update: prior · evidence considered · dependence concerns · posterior · confidence range · reason. **Do not use mathematical language to disguise subjective judgment** — state plainly that these encode judgment, and name the single most important input to the update. ### 5. Scan for Biases and Fallacies Identify only when warranted by the text: confirmation bias · selection bias · survivorship bias · availability bias · authority bias · motivated reasoning · fundamental attribution error · false dilemma · straw person · equivocation · circular reasoning · hasty generalization · anecdotal fallacy · appeal to popularity · appeal to tradition · appeal to novelty · genetic fallacy · composition or division error · correlation-causation error · base-rate neglect · moving the goalposts · unfalsifiable framing. For each: cite the claim or source · explain the reasoning · state how strongly it affects the conclusion · **distinguish a genuine fallacy from a rhetorical weakness**. Also record **counter-observations in the author's favor** — places where the author allows a counter-argument to win, concedes a weakness, or reports evidence against their own position. These temper bias findings and are easy to miss. ### 6. Attempt Repairs Before rejecting a weak claim, attempt the strongest reasonable repair: narrowing scope · refining a definition · replacing a causal claim with a correlational one · adding a missing condition · separating descriptive and prescriptive claims · acknowledging exceptions · reducing certainty · specifying the relevant population or context. State whether the repaired claim remains faithful to the author's larger argument, and what the repair costs the author rhetorically. Mark claims that are **not repairable** and say why. ### 7. Separate Attribution from Analysis Use consistently: **Author says** · **Author implies** · **Evidence shows** · **We infer** · **We conclude** · **Still uncertain**. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 8 — Systems, Context, Historiography Place **{{TITLE}}** within its broader systems and intellectual context. ## Tasks Analyze: historical context · institutional context · political and economic incentives · technological context · cultural assumptions · disciplinary traditions · relevant schools of thought · major debates · predecessor arguments · competing interpretations · later developments that affect the book · whose perspectives shaped the record · whose perspectives are missing. Distinguish: context available to the author · context added after publication · current interpretation · speculative explanation. Create a historiography or intellectual-lineage map when applicable. **Label any anachronistic comparison as convergent rather than causal** unless influence is documented. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 9 — DEIB, Multicultural, Accessibility, Reading-Level Audit Audit for diversity, equity, inclusion, belonging, multicultural applicability, accessibility, and reading demands. **Do not assume that demographic representation alone establishes fairness or usefulness.** ## Tasks Evaluate: whose experiences appear · whose are absent · who receives agency · who becomes an object of analysis · universal claims based on narrow samples · cultural, class, gender, racial or ethnic, religious, and geographic assumptions · disability framing · neurodiversity framing · language accessibility · jargon burden · assumed education · digital or financial access · practical barriers to applying the advice. Create: an inclusion strengths section · an exclusion or omission risks section · a multicultural transferability table · an accessibility audit · a reading-level estimate · recommendations for supplementary perspectives. For the strengths section, look for structural rather than rhetorical inclusion — guaranteed representation, procedural protection for minorities, mechanisms that survive a change of leadership. These count for more than stated commitments. For the reading-level estimate, distinguish **syntactic difficulty** from **reference density**. A reader can follow every sentence and still miss the argument when it runs through unexplained precedents. Separate textual evidence from reader inference. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 10 — Notes Pipeline Convert the reading analysis into a structured notes system. ## Tasks ### 1. Fleeting Notes Capture unresolved reactions, questions, connections, and reminders. ### 2. Literature Notes Concise notes tied directly to claims · concepts · evidence · chapters · clusters · quotations. Each retains source attribution. ### 3. Permanent Notes Standalone, atomic notes that: express one idea · use original wording · remain useful outside the book · link to supporting literature notes · identify uncertainty · avoid overstating the evidence. Include a stated **confidence** and a **scope and conditions** block. A permanent note that does not say where it stops applying will be over-applied later. ### 4. Structure Notes Maps of content for: the book · major themes · related projects · related disciplines · claim clusters · unresolved questions. Check existing MOCs for adjacency before creating new ones, and add **reciprocal** links — a one-way link is half a connection. ### 5. Attribution Audit Confirm that every quotation, paraphrase, claim, and inference has the correct author or source. **Do not attribute the system's conclusions to the book's author.** Produce an explicit "do not attribute to the author" list covering: reader-inferred claims (RI) · anachronistic comparisons · cross-domain analogies · every permanent note. ## Output Requirements Return Obsidian-ready Markdown. Include suggested filenames and links. Do not create duplicate notes unnecessarily — but do split permanent notes into their own files, since atomic notes embedded in a working note cannot be linked to or resurfaced. --- # PROMPT 11 — Teaching Pack Turn the analysis into a teaching resource. ## Tasks Create: audience description · learning objectives · prerequisite knowledge · key vocabulary · lesson sequence · discussion questions · misconception checks · case studies · activities · reflection prompts · assessment options · facilitator cautions · accessibility adaptations · multicultural adaptations · further reading. Distinguish: what the book argues · what the evidence supports · what remains disputed · what learners should examine critically. **Do not teach disputed claims as settled facts** — including the analysis's own conclusions. Where an inferential question is genuinely live, teach it as live; those are usually the best teaching moments in the material. Facilitator cautions should name: where the analogies will run away with the room · what coverage limits to disclose · where the material may be personally sensitive to participants · and anything that must not be attributed to the author. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 12 — Action, PARA, Experiments, Drift Monitoring Convert useful conclusions into responsible actions. ## Tasks ### 1. Action Inventory Identify: actions to take · actions to consider · actions to avoid · questions requiring more evidence · ideas useful only in specific contexts. Under "avoid," name the **most likely misuse of this analysis** explicitly. ### 2. PARA Routing Assign material to Projects · Areas · Resources · Archives, with a brief rationale for each routing decision. It is a valid result for nothing to route to Projects. ### 3. Experiments Design small, reversible experiments. | Experiment | Related claim | Hypothesis | Action | Measure | Duration | Stop condition | Review date | | --- | --- | --- | --- | --- | --- | --- | --- | Avoid testing advice that creates unreasonable medical, legal, financial, interpersonal, or safety risks. Where an experiment involves other people, conduct it as ordinary conversation and disclose what you are doing — never as covert study. Where a book's claims are historical and not directly testable, test the **transferred** propositions from the permanent notes instead. ### 4. Decision Rules Define what outcomes would lead to: adoption · adaptation · further testing · rejection · deferral. Name which permanent note gets revised under a rejection outcome. ### 5. Drift Monitoring For each claim that may age quickly: what could change · sources to monitor · review frequency · expiration or reassessment date · conditions triggering early review. State separately which claims **will not drift**, so they are not re-reviewed pointlessly. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # PROMPT 13 — Visual Thinking Pack Translate the analysis into visual structures suitable for Excalidraw, Mermaid, or another visual-notes tool. ## Tasks Create specifications for: book map · argument map · claim dependency graph · evidence map · terminology map · causal-loop diagram · timeline · stakeholder map · systems map · comparison matrix · decision tree · concept map · action map. **Include only visuals appropriate to the book, and say which you omitted and why.** For each visual provide: title · purpose · nodes · connections · grouping · labels · uncertainties · source claim IDs · source highlight IDs · recommended layout. Provide Mermaid syntax where Mermaid can represent the visual effectively. For Excalidraw-oriented visuals, provide an implementation-ready layout description. Encode coverage gaps and weak inferential steps **visually** — dashed borders, warning nodes — so the diagram cannot be read as more confident than the analysis. ## Output Requirements Return Obsidian-ready Markdown that can be appended to the working note. --- # Prompts Not Run During This Session Use this format for each unexecuted prompt: * **Prompt {{PROMPT_NUMBER}} — {{PROMPT_NAME}}:** {{STATUS_OR_REASON}} Statuses: intentionally skipped · not relevant to this book · waiting for more source material · deferred to another session · blocked by missing access · not yet run. --- # Session Completion Check Before closing the session: 1. Confirm which prompts ran. 2. Confirm which prompts produced usable output. 3. List any prompts that partially failed, and how they were adapted. 4. Identify missing source material, ranked by consequence. 5. Identify assumptions introduced during the session. 6. Confirm the next prompt in the chain. 7. Update the YAML fields. 8. Preserve correct attribution throughout. 9. Do not claim the author said something that appears only in system analysis. 10. Record corrections in the working note rather than silently changing prior conclusions. --- ## Changelog **v2 — 2026-07-25.** Added the Layer 1 substitution rule and coverage-note requirement (Prompt 0); inferred-input labeling (Prompt 1); claim-source labels EA/IA/Q3P/RI/UI with an attribution guard (Prompt 4); non-vacuous falsifiers and an "unfalsifiable as stated" verdict (Prompt 4); dependence-between-sources as the dominant Bayesian constraint and permission to scope down the quantitative apparatus (Prompt 5); evidence-independence summary (Prompt 6); repair attempts before rejection and counter-observations in the author's favor (Prompt 7); convergent-vs-causal labeling for anachronistic comparison (Prompt 8); structural-inclusion emphasis and the syntax-vs-reference-density distinction (Prompt 9); confidence and scope blocks on permanent notes, reciprocal MOC links, and an explicit do-not-attribute list (Prompt 10); instruction not to teach the analysis's own conclusions as settled (Prompt 11); most-likely-misuse callout and transferred-proposition experiments (Prompt 12); omitted-visuals disclosure and visual encoding of uncertainty (Prompt 13); session completion check expanded to rank missing material by consequence. **v1 — 2026-01-07.** Archived at [[Work the Book (v1 archived 2026-07-25)]]. ```` </details>