# Docs Like Code > [!summary] Recommendation > Keep this as a foundational operating guide, not a current setup manual. Gentle's core model still holds: store documentation source in version control, make changes small and reviewable, automate deterministic checks and builds, require human technical review, and publish through a controlled pipeline. Read the planning, review, testing, versioning, and lessons-learned sections closely. Treat the GitHub Pages tutorial, prices, authentication instructions, branch names, API-tool survey, and product-specific commands as historical. **Rating: 3.5/5 overall; 4.5/5 for the operating model, 2/5 for current implementation guidance.** ## Review synthesis *Docs Like Code* gives documentation work an engineering control system. Its lasting contribution is not Markdown, GitHub, Jekyll, Gerrit, or any named tool. It is the claim that documentation quality improves when teams make source observable, changes traceable, review responsibilities explicit, build failures reproducible, and publishing repeatable. The book is at its best when it explains how those controls work together. Version control creates history and parallel work. Small patches make review possible. Issue links connect a change to a stated reader problem. Automated checks remove mechanical review work. Preview builds let reviewers compare source and output. Human technical reviewers test meaning and task accuracy. Versioned publishing helps readers avoid instructions for the wrong release. Contributor and style guides reduce hidden rules. Its proof is narrower than its advice. OpenStack supplies most of the detailed experience, and Rackspace supplies another large share. The examples show feasibility at scale, but they do not isolate causes. Statements about better reviews, lower cost, higher respect, or better documentation often lack comparison groups, outcome definitions, and measures of reader success. The strongest conclusion is therefore practical: the system is coherent and testable. The book does not establish that adopting the system alone produces the promised organizational results. The 2017 tool layer has aged. GitHub Pages gained HTTPS for custom domains in 2018. GitHub stopped password authentication for Git operations in 2021. New repositories now commonly use `main`, and GitHub Pages can deploy through GitHub Actions with explicit permissions and environments. OpenAPI has advanced from the book's Swagger-era account to version 3.2.0. These changes do not overturn the model; they demonstrate the model's own demand for versioned, maintained documentation. The larger omission is access. The book notices English-first review, translation, contributor fear, tool cost, and command-line difficulty. It gives little attention to disability access, screen-reader and keyboard behavior, cognitive load, low-bandwidth use, contributor safety, or the way repository permissions concentrate publishing power. A modern adoption should treat accessibility, security, maintenance ownership, and reader-task testing as release gates, not optional polish. --- ## Prompt 0 - retrieval, provenance, and Layer 1 ### Source record | Field | Result | |---|---| | Supplied artifact | Local PDF | | PDF metadata | *Docs Like Code*, Anne Gentle, second edition, 2017 | | ISBN | 978-1-387-07512-6 | | License | Creative Commons Attribution-ShareAlike 4.0 | | Integrity | 197 pages, unencrypted, no JavaScript, extractable text | | Extracted text | 24,724 words across 3,915 lines | | Coverage | Every page reviewed; blank/image-only pages checked in context | | Visual inspection | Representative prose, decision-table, automated-test table, and publishing pages rendered and inspected | | Reader layer | No Readwise access or local Reader CLI was available; no supplied annotations | | External layer | Current primary sources used only for drift checks | ### Layer 1 substitution The local PDF replaces Readwise as Layer 1 under the canonical Work the Book v2 rule. Page anchors use `P-####`, based on the physical PDF page number. Because no reader highlights exist, these anchors record system selection, not reader emphasis. ### Coverage and anchor map | Anchor range | Section | Coverage | |---|---|---| | P-0001-P-0015 | Contents, copyright, foreword, author and contributors | Read in full | | P-0016-P-0040 | Introducing docs like code; definition, reasons, goals | Read in full | | P-0041-P-0050 | Planning source and site organization | Read in full | | P-0051-P-0066 | REST API documentation | Read in full | | P-0067-P-0073 | Wikis compared with repository workflows | Read in full | | P-0074-P-0088 | Workflow selection | Read in full | | P-0089-P-0098 | Authoring and local builds | Read in full | | P-0099-P-0117 | Automated builds and publishing infrastructure | Read in full | | P-0118-P-0141 | Review, testing, coaching, and copy editing | Read in full | | P-0142-P-0159 | Versions, locales, releases, and archives | Read in full | | P-0160-P-0181 | GitHub Pages and Git tutorial | Read in full; commands treated as historical | | P-0182-P-0193 | Lessons learned and measurement | Read in full | | P-0194-P-0197 | Git glossary | Read in full | ### System-selected source index | ID | Page | Why it matters | |---|---:|---| | P-0018 | 18 | Defines the four-part framework: version, build, review, publish | | P-0026 | 26 | Claims shared tooling can support collaboration and recognition | | P-0032 | 32 | Connects automated checks with two-human review in OpenStack | | P-0042 | 42 | Makes repository placement a user, contributor, reviewer, and release decision | | P-0059 | 59 | Separates generated API reference from onboarding and task guidance | | P-0066 | 66 | Concedes that the model alone does not guarantee successful API docs | | P-0075 | 75 | Says code-adjacent docs should use the development workflow | | P-0092 | 92 | Requires authors to inspect rendered output, not only source | | P-0104 | 104 | Explains why preview builds reduce contributor setup cost | | P-0105 | 105 | Names premature or incomplete publication as an automation risk | | P-0123 | 123 | Provides a review checklist tied to testable tasks and audience context | | P-0129 | 129 | Separates voting from non-voting automated checks | | P-0132 | 132 | Rejects unreliable automated grammar and spell checks as merge gates | | P-0133 | 133 | Places technical accuracy under human review | | P-0145 | 145 | Treats unsupported versions and legal retention needs as design constraints | | P-0156 | 156 | Distinguishes test, staging, and production documentation environments | | P-0185 | 185 | Uses style guidance to remove recurring review disputes | | P-0187 | 187 | Makes contribution and review expectations explicit | | P-0191 | 191 | Calls for both reader-output and contributor-process measures | ### Missing source material, ranked by consequence 1. **Reader annotations and stated purpose:** highest consequence for personalization; no claim below is presented as the reader's prior belief. 2. **Bibliography with stable citations:** high consequence for auditing market, cost, and effectiveness claims. 3. **Independent outcome studies:** high consequence for causal claims about quality, cost, respect, and productivity. 4. **Current edition or maintained errata:** high consequence for operational commands; mitigated by primary-source drift checks. 5. **Representative accessibility evaluation:** medium-high consequence for adoption across contributor and reader populations. --- ## Prompt 1 - reading contract, priors, and open questions > [!note] Inferred inputs > No purpose, prior-belief list, depth, or DEIB goal accompanied the PDF. I inferred an analytical purpose: decide which docs-as-code practices remain useful for technical communication, WordPress, developer education, and open-source work in 2026. I assumed practitioner-level existing knowledge and a focus on accessibility, governance, maintenance, and evidence quality. These are system assumptions, not reader beliefs. ### Reading contract - **Decision:** Separate durable operating controls from expired tool instructions. - **Practical use:** Build or audit documentation workflows without confusing pipeline health with reader success. - **Success criteria:** Identify adopt, adapt, test, and reject decisions with traceable source anchors. - **Evidence that would change the conclusion:** Comparative task-success, defect, cycle-time, and contributor-retention data showing that another workflow performs better under similar conditions. - **What the book cannot establish:** Universal causal effects, current GitHub procedures, current prices, or accessibility compliance. - **Constraint:** One consolidated vault note must contain the full Prompt 0-13 output. ### Prior-belief seed table | Placeholder | Initial belief | Confidence | Reason | Evidence needed | |---|---|---:|---|---| | PR-A | Version control improves traceability | High | Change history and rollback are direct system properties | Failure and recovery comparisons | | PR-B | Small changes improve review quality | Moderate | Smaller diffs reduce review load | Error-detection studies by diff size | | PR-C | Automated builds reduce publishing toil | High | Automation removes repeated manual steps | Cycle-time and failure-rate records | | PR-D | Automation alone improves content quality | Low | Mechanical validity differs from reader success | Task testing before and after adoption | | PR-E | Shared tooling improves writer-developer collaboration | Moderate | Shared context can reduce handoffs | Participation and review-network data | | PR-F | Docs in the code repository stay synchronized | Moderate | Proximity supports coordination but does not force it | Staleness comparisons across repo models | | PR-G | Contributor count reflects documentation success | Low | Counts omit quality, burden, and reader outcomes | Retention, acceptance, quality, and task data | | PR-H | Human technical review remains necessary | High | Meaning and environment validity resist deterministic checks | Reliable end-to-end automated task verification | | PR-I | One workflow fits every documentation set | Very low | Audience, release, security, and contributor needs differ | Broad cross-context success evidence | | PR-J | Reader and contributor accessibility must be release criteria | High | Exclusion defeats effective use and contribution | Representative accessibility test results | ### Open questions #### Definitions and mechanisms - Which properties are required before a workflow counts as docs as code? - Does repository proximity improve synchronization, or do ownership and gates do the work? - When does a docs build prove quality, and when does it only prove renderability? - Which content belongs beside code, and which needs a separate governance boundary? #### Evidence and credibility - What reader outcomes changed after OpenStack adopted each practice? - How much of the reported scale came from project growth rather than workflow quality? - Are contribution counts independent of organizational incentives and access rules? - Which claims survive outside large, mature open-source infrastructure projects? #### Application and failure modes - What is the minimum viable pipeline for a small WordPress or documentation project? - Which checks should block publication, warn reviewers, or run after release? - How does a team prevent an always-green build from hiding wrong instructions? - Who owns build dependencies, security updates, broken links, redirects, and archived versions? - When does shared tooling shift unpaid maintenance onto writers or contributors? #### Access, language, and power - Can keyboard, screen-reader, low-vision, and low-bandwidth users complete the contributor path? - Does Git fluency become an unrelated gate to subject-matter contribution? - How are non-English contributions reviewed without shame or assimilation pressure? - Who can approve, merge, publish, revert, or retract, and how can that power be challenged? - Do analytics capture failures experienced by minority user groups, or average them away? ### Drift assumptions The book's principles are fixed; their evaluation and implementation are not. Authentication, branch conventions, CI systems, API specifications, pricing, supported runtimes, security practice, accessibility standards, and hosting behavior need current verification before use. Reassess implementation guidance every six months and the operating model yearly. --- ## Prompt 2 - inspectional reading ### Central project Gentle asks how documentation teams can borrow software-development controls without giving up writing judgment or reader focus. Her answer is a four-part framework: version source, build artifacts automatically, review with trusted people and tests, and publish with little manual intervention. Planning, information architecture, API description, workflow design, contribution guidance, versions, translation, and measurement sit around that spine. ### Book map | Section | Purpose | Main contribution | Main limit | |---|---|---|---| | Introducing docs like code | Define the approach and sell its value | Four-part framework and collaboration goals | Benefits are broader than the supplied evidence | | Plan for docs like code | Match source structure to audience and team needs | Repository decisions as information architecture and governance | OpenStack dominates the examples | | REST API docs | Apply the method to fast-changing reference material | Generated reference must be paired with use cases and onboarding | API ecosystem snapshot is from 2017 | | What about wikis? | Compare lower-barrier authoring with repository controls | Names real usability, security, review, and reuse tradeoffs | Frames the choice too tightly around GitHub-era tooling | | Optimize workflows | Select, author, build, review, test, and publish | Strong operational detail and review discipline | Product instructions and terminology have drifted | | Tutorial | Give newcomers a first repository and Pages workflow | Reveals the full contributor journey and likely friction | Not safe as current setup guidance | | Lessons learned | Address culture, contributor support, and measurement | Style guide, contribution guide, CI, respect, outcome testing | Reader success measures remain underdeveloped | | Glossary | Define Git terms | Lowers vocabulary barriers | Uses older default-branch language | ### Provisional summary *Docs Like Code* argues that technical documentation should use software-style controls: source in version control, automated builds, trusted review, tests, and low-touch publication. The method can make changes traceable, enable parallel contribution, expose previews, connect fixes to issues, and version output with the product. Gentle treats repository structure as both information architecture and governance, and she warns that tool choice must follow audience, contributor, reviewer, security, release, and translation needs. OpenStack supplies the book's main example of high-volume collaborative documentation. The operating model remains useful, but the evidence supports feasibility more strongly than universal effectiveness. The 2017 tutorial and product details are obsolete in several material ways. A current implementation must add accessibility, supply-chain security, maintenance ownership, task-based reader testing, and current platform guidance. ### Reading hotspots and strategy Read P-0018-P-0040 for the model, P-0041-P-0050 for architecture decisions, P-0099-P-0141 for build/review/test controls, and P-0142-P-0159 for versioning and release design. Read P-0182-P-0193 for adoption conditions. Sample the API section if API docs are in scope. Skip the tutorial as instruction; retain it as a historical contributor-journey specimen. This selective deep read changes to a full reread only if designing a migration or teaching the history of the practice. --- ## Prompt 3 - classification and controlled vocabulary ### Classification - **Domain:** technical communication and documentation engineering - **Subdomains:** developer documentation, API documentation, open-source contribution, CI/CD, content operations - **Genre:** practitioner handbook with tutorial and organizational advocacy - **Argument type:** prescriptive operating model supported by cases and implementation examples - **Primary method:** practitioner experience, process explanation, tool comparison, and OpenStack case material - **Not:** controlled evaluation, comprehensive history, security guide, or accessibility standard ### Controlled vocabulary | Term | Author's meaning | Operational definition here | Equivocation risk | Example / counterexample | Evidence | |---|---|---|---|---|---| | Docs like code | Version, build, trusted review, low-touch publish | A documentation change system with traceable source, reproducible output, explicit gates, and release control | Can shrink to “Markdown in Git” | PR with preview and tests / unreviewed Markdown upload | P-0018 | | Version control | Recorded source history and parallel work | A system that identifies, compares, restores, and branches revisions | History alone does not create governance | Git history / dated files in email | P-0018, P-0150 | | Build | Parse source into a deliverable | Reproducibly transform source and dependencies into reviewable output | “Build passed” can sound like “content is correct” | Sphinx HTML / manual copy-paste export | P-0101 | | Deploy or publish | Copy output to an audience-facing location | Release an identified artifact through controlled permissions | Publishing can occur without discoverability or usability | Protected Pages deployment / local preview | P-0099, P-0156 | | Review | Compare a change and judge it before merge | Check intent, source, rendered output, technical behavior, and user effect | Approval can become ceremonial | Tested PR review / PDF sign-off | P-0031, P-0123 | | Voting test | Automated result that blocks merge | Deterministic check with a documented, low-false-positive failure rule | Teams may make subjective lint blocking | Broken build / disputed grammar preference | P-0129-P-0132 | | Non-voting test | Automated warning that does not block | Informational check needing human judgment or tolerance for transient failure | Warnings can be ignored indefinitely | External-link report / silent failure | P-0129-P-0131 | | Technical accuracy | Instructions match actual product behavior | Representative users can complete the task in a stated environment | Correct commands may still omit prerequisites | Clean-environment task pass / syntactically valid wrong command | P-0123, P-0133 | | Contributor | Person proposing or reviewing source changes | Anyone who can enter the governed contribution path | Git activity can erase non-code labor | Subject expert PR / uncredited interview input | P-0026-P-0029 | | Long-tail contribution | Small, specialized knowledge contribution | Narrow correction or addition from a domain expert | Niche volume does not guarantee maintenance | Edge-case fix / abandoned fragment | P-0028-P-0030 | | Documentation bug | Tracked defect or requested change | Reproducible mismatch between reader need and current content | Feature requests and errors need different priority | Wrong command / preference for another theme | P-0029-P-0030 | | Preview | Rendered candidate output before publication | Artifact built from the exact proposed revision and visible to reviewers | Preview can differ from production | PR artifact / editor approximation | P-0083, P-0104 | | Documentation version | Reader-visible relation between docs and supported product state | Identifiable docs release with support, retention, and redirect rules | Branch, product, artifact, and URL versions can diverge | `/4.1/` docs / undated “latest” snapshot | P-0142-P-0159 | | Style guide | Written language and markup conventions | Rules that resolve recurring disputes and enable safe checks | Style compliance can displace task accuracy | Terminology rule / blocking a useful fix over tone | P-0185 | | Contributor guide | Entry, build, test, review, and decision expectations | A maintained contract for participation and authority | Documentation does not remove actual barriers | Tested setup guide / aspirational README | P-0187 | ### Category-error watchlist - **Present:** build success can be mistaken for content correctness. - **Present:** more contributors can be mistaken for better reader outcomes. - **Present:** an OpenStack success story can be generalized to unlike organizations. - **Present:** tool affordability can be mistaken for low total maintenance cost. - **Present:** repository proximity can be mistaken for synchronization. - **Present:** a measured activity can be mistaken for quality or causality. - **Absent:** the book explicitly rejects one-size-fits-all tooling and admits that docs as code cannot guarantee API-doc success. - **Not applicable:** theological, medical, and legal category errors. --- ## Prompt 4 - claims, evidence expectations, and dependencies ### Claims inventory Source labels: **EA** explicit author claim; **IA** implied author claim; **RI** system inference, not the author's sentence. | ID | Claim | Source | Type | Expected evidence | Falsifier | Anchor | |---|---|---|---|---|---|---| | C-001 | Docs as code requires versioned source, automated builds, trusted review, and low-touch publication. | EA | Definitional | Direct definition and operational examples | A substantially different definition used consistently in the book | P-0018 | | C-002 | Shared development tooling can improve writer-developer collaboration. | EA | Causal | Network, cycle-time, interview, and review-quality comparisons | Collaboration worsens or excludes more people without compensating gains | P-0026-P-0028 | | C-003 | Small, specialist contributions improve coverage of complex products. | EA | Causal | Accepted-change quality and maintenance data | Niche additions create more inconsistency or abandonment than value | P-0028-P-0030 | | C-004 | Issue-linked changes make documentation repair easier to judge. | EA | Practical | Reviewer accuracy and traceability comparisons | Linked issues do not improve scope or acceptance decisions | P-0121 | | C-005 | Repository placement should follow reader, contributor, reviewer, release, size, and translation needs. | EA | Prescriptive | Successful comparisons across repo models | One placement consistently outperforms across those constraints | P-0042-P-0044 | | C-006 | Keeping docs near code can reduce synchronization problems. | EA | Causal | Staleness and coordinated-change data | Co-located docs remain as stale as separated docs under comparable ownership | P-0075 | | C-007 | Generated API reference is insufficient for onboarding and support. | EA | Evaluative | Task tests across reference-only and guided docs | Representative users succeed equally with reference alone | P-0059 | | C-008 | Workflow complexity should grow with contribution, review, release, and publishing complexity. | EA | Prescriptive | Failure and overhead comparisons | More complex workflows add cost without controlling real risk | P-0074-P-0088 | | C-009 | Authors and reviewers need rendered previews, not only source diffs. | EA | Practical | Defect detection by source-only versus source-plus-preview review | Preview adds no unique defects or user-effect information | P-0092, P-0104 | | C-010 | CI/CD reduces manual build work and supports high change volume. | EA | Causal | Build time, queue, failure, and labor records | Manual workflows match throughput and failure control at equal cost | P-0099-P-0105 | | C-011 | Automation can publish incomplete work unless human review and rules constrain it. | EA | Causal | Incident and gate-bypass records | Automated pipelines prevent semantic or completeness failures without human judgment | P-0105 | | C-012 | Deterministic checks should block; judgment-heavy checks should warn or remain human. | IA | Methodological | False-positive, false-negative, and review-cost data | Subjective blocking checks remain reliable across contexts | P-0129-P-0132 | | C-013 | Human technical review is necessary for task accuracy. | EA | Prescriptive | Clean-environment and expert task tests | Automated end-to-end tests reliably validate meaning and representative user success | P-0133 | | C-014 | Style and contributor guides reduce hidden rules and repeated review conflict. | EA | Causal | Review-comment and onboarding comparisons | Guides add maintenance without improving consistency or entry | P-0185-P-0188 | | C-015 | Documentation needs explicit version, locale, archival, and release policies. | EA | Prescriptive | Wrong-version incidents, findability, legal and support data | Unversioned delivery creates no material reader or organizational risk | P-0142-P-0159 | | C-016 | Shared tooling raises organizational respect for documentation work. | EA | Causal | Status, decision-rights, compensation, and participation evidence | Tool convergence occurs without changes in power or recognition | P-0026-P-0028 | | C-017 | Contributor and web analytics can guide workflow improvement. | EA | Methodological | Defined metrics tied to decisions and reader outcomes | Metrics drive gaming or miss important failures | P-0191-P-0192 | | C-018 | Current adoption must add accessibility, security, and maintenance controls absent from the book. | RI | Prescriptive | Current standards, platform controls, and representative tests | These controls add no protection or access in the target context | Current comparison layer | > [!warning] Attribution guard > C-018 is a system conclusion. Do not quote or attribute it to Gentle. ### Evidence pattern The book supplies direct definitions, implementation descriptions, process logic, a few quantitative scale claims, and repeated OpenStack cases. It rarely supplies independent comparisons, raw data, sampling details, reader task-success results, or competing cases. Evidence is strongest for “this can be built and operated” and weakest for “this causes higher quality, lower cost, or greater respect.” ### Claim dependency graph ```mermaid flowchart TD C1["C-001: Four-part framework"] --> C5["C-005: Context selects structure"] C1 --> C8["C-008: Context selects workflow"] C5 --> C6["C-006: Proximity may reduce drift"] C8 --> C9["C-009: Preview proposed output"] C8 --> C10["C-010: Automate builds"] C9 --> C13["C-013: Human task review"] C10 --> C11["C-011: Automation needs constraints"] C11 --> C12["C-012: Match gate strength to test reliability"] C13 --> R["Responsible publication"] C12 --> R C15["C-015: Version and archive policy"] --> R C18["C-018: Modern access and security controls"] -. system repair .-> R ``` **Load-bearing claims:** C-001, C-009, C-011, C-012, C-013, and C-015. The weakest bridge is C-002/C-016: shared tooling may support collaboration and status, but the book does not show that the tool change causes either. --- ## Prompt 5 - quantitative rigor ### Policy Use numerical confidence only as a visible record of judgment. Do not treat repeated OpenStack anecdotes as independent observations. Give more weight to direct system properties, reproducible demonstrations, representative task tests, and independent comparisons. Use qualitative updates when denominators or comparable conditions are missing. ### Confidence bands | Label | Range | |---|---:| | Very low | 0-20% | | Low | 21-40% | | Uncertain | 41-60% | | Moderate | 61-75% | | High | 76-90% | | Very high | 91-100% | ### Priors and posteriors | Claim | Prior | Main evidence | Update | Posterior | Reason | |---|---:|---|---|---:|---| | C-002 shared tools improve collaboration | 65 | OpenStack examples and mechanism | Small increase | 70 | Plausible, but correlated and context-bound | | C-004 issue links improve judgment | 70 | Direct traceability mechanism | Moderate increase | 80 | The reviewer can compare stated problem and change | | C-006 proximity reduces drift | 65 | Coordination logic, no comparison | No meaningful update | 65 | Ownership and gates may explain the effect | | C-007 reference alone is insufficient | 75 | Task model and examples | Moderate increase | 82 | Reference and learning tasks differ directly | | C-009 previews improve review | 75 | Source/output mismatch mechanism | Moderate increase | 85 | Rendered defects are invisible in source-only review | | C-010 CI/CD reduces manual build work | 80 | Direct automation property and scale case | Moderate increase | 88 | Repeated manual steps are mechanically removed | | C-012 gate strength should track reliability | 80 | False-positive reasoning and book concession | Small increase | 86 | A blocking check must have dependable semantics | | C-013 human task review remains necessary | 85 | Meaning and environment limits of checks | Small increase | 89 | Source reports no automated substitute | | C-016 shared tooling raises status | 50 | Contribution-count and equality claims | Small decrease | 45 | Activity visibility is not organizational power | | C-017 analytics guide improvement | 65 | Contributor examples, few reader metrics | No meaningful update | 65 | Useful only when a measure is tied to a decision | ### Calibration warnings - **Correlated evidence: high.** Many examples come from the same OpenStack system and authors. - **Selection and survivorship bias: high.** Successful, visible open-source programs dominate. - **Unavailable denominators: high.** Counts of changes and contributors lack eligible-population and quality context. - **Proxy risk: high.** Commits, reviews, and build passes stand in for reader success. - **Historical drift: high.** Tool behavior, prices, and procedures have changed. - **Publication bias: moderate.** Failed migrations and abandoned pipelines receive less detail. - **False precision: moderate.** Exact counts document scale but do not prove causal effectiveness. - **P-values and statistical significance: not applicable.** The book reports no inferential statistical analysis. --- ## Prompt 6 - analytical scaffold and evidence ledger ### Section analysis | Section | Thesis | Evidence | Counterexample or gap | Role in spine | |---|---|---|---|---| | Introduction | Shared engineering controls can improve docs work | OpenStack, Rackspace, tool history | Teams with different access and release needs | Defines problem and promise | | Planning | Source structure must follow user and team constraints | Decision factors and OpenStack evolution | No systematic cross-project comparison | Adds conditional design | | API docs | Description formats and collaboration can support API quality | Framework survey and migration case | OpenAPI retrofit failure is context-specific | Tests the model on specialty content | | Wikis | Wikis trade control and automation for lower entry cost | Feature comparison | Modern collaborative platforms blur the categories | Keeps an alternative alive | | Workflow | Automation, preview, review, and versioning form a pipeline | Detailed implementation and OpenStack operations | Tool and security drift | Supplies the operating system | | Tutorial | Practice reduces Git and publishing friction | Step-by-step exercise | Current procedure is obsolete | Exposes onboarding requirements | | Lessons | Adoption requires culture, guidance, authority, and measures | Practitioner reflection | Reader outcomes remain thin | Adds social conditions and feedback | ### Argument spine 1. Software documentation changes quickly and depends on technical knowledge. 2. Isolated writing and manual publishing weaken traceability, review, and speed. 3. Version control, builds, review, tests, and deployment can control those risks. 4. The workflow must match audience, contributor, release, security, and localization conditions. 5. Guides, coaching, and explicit authority make participation possible. 6. Reader and contributor measures should drive iteration. 7. Therefore, teams should adopt the controls selectively and improve them with evidence. **Weakest link:** the move from a coherent, feasible control system to broad claims about quality, cost, collaboration, and respect. Repair it with baseline and post-adoption measures, comparable teams or periods, representative reader task tests, and explicit alternative explanations. ### Evidence ledger | ID | Claims | Type | Independence | Quality | Limit | |---|---|---|---|---|---| | E-01 | C-001 | Direct definition | Author-originated | A for attribution | Does not establish effectiveness | | E-02 | C-002-C-006 | OpenStack cases | Low | C | Same ecosystem and authors recur | | E-03 | C-007 | API task model and examples | Moderate | B | No direct task-test data | | E-04 | C-008-C-013 | Process logic and implementation | Moderate | B | Mostly feasibility and mechanism | | E-05 | C-010 | High-volume merge counts | Low | C | No baseline, denominator, or quality outcome | | E-06 | C-014 | Practitioner guidance | Low | C | Plausible but unevaluated | | E-07 | C-015 | Version and release failure scenarios | Moderate | B | Risks are direct; frequency is unknown | | E-08 | C-016 | Contribution visibility and equality claims | Low | D | Status and power are not measured | | E-09 | C-017 | Contributor-metric examples | Low | C | Reader metrics are underdeveloped | | E-10 | C-018 | Current official platform/spec sources | Independent | A for drift facts | Does not evaluate every current tool | Only E-10 is fully independent of the book's author network. No independent source reviewed here refutes the operating model; current platform sources refute several operational details. ### Completion criteria for Prompt 7 Met: full coverage, stable anchors, claims and source labels, falsifiers, evidence ledger, dependency map, drift checks, and explicit reader-input limits. --- ## Prompt 7 - x-ray analysis and fair criticism ### Strongest reconstruction **Author says:** Documentation is a software-adjacent product whose source, transformations, review, and releases need explicit controls. **Author implies:** Teams can reduce handoff failure and increase participation when docs enter familiar development systems. **Evidence shows:** The approach can support high-volume work in OpenStack and can make changes, builds, reviews, and releases observable. **We conclude:** Adopt the control model, test its organizational benefits locally, and replace all dated implementation instructions. ### Major-claim evaluation | Claim | Support | Grade | Strongest objection | Repair | Current conclusion | |---|---|---:|---|---|---| | C-001 framework definition | Direct and consistent | A | A definition is not an outcome | None needed | Clear and useful | | C-002 collaboration | Mechanism and cases | C | Git can exclude contributors | “Can improve under supported access conditions” | Test locally | | C-004 issue-linked change | Direct traceability | B | Poor issue framing still misleads | Require reproducible acceptance criteria | Adopt | | C-005 context selects structure | Multiple concrete factors | B | Factors are not weighted | Use a local decision record | Adopt | | C-006 code proximity reduces drift | Plausible mechanism | C | Ownership and gates may dominate | “Proximity lowers coordination cost when ownership exists” | Adapt | | C-007 reference is insufficient | Task distinction | B | Expert users sometimes need only reference | Scope to onboarding and unfamiliar tasks | Adopt | | C-009 previews improve review | Direct visibility mechanism | B | Preview-production parity can fail | Build preview from pinned production path | Adopt | | C-010 CI/CD reduces toil | Direct automation and case scale | B | Pipeline maintenance can exceed saved labor | Measure total maintenance and cycle time | Adopt selectively | | C-011 automation risk | Explicit concession and mechanism | B | Strong end-to-end gates can reduce human work | Keep human judgment where semantics remain open | Adopt | | C-012 gate reliability | Voting/non-voting distinction | B | Teams can tolerate rare false positives for safety | Set documented severity and override policy | Adopt | | C-013 human technical review | Explicit guidance | B | Executable docs can test more than the book assumes | Automate execution, retain representative task review | Adopt | | C-015 version policy | Detailed failure cases | B | Small current-only products may need little machinery | Scale retention and branching to actual support risk | Adopt | | C-016 status improvement | Contribution visibility | D | Visibility does not transfer authority | Measure decision rights and recognition | Unproven | | C-017 analytics | Contributor examples | C | Metrics invite gaming and omit user harm | Tie each metric to a user outcome and decision | Adapt | **Grade distribution:** A: 1; B: 8; C: 4; D: 1; F: 0. The pattern supports a practitioner framework with sound mechanisms, not a proven organizational intervention. ### Biases, rhetorical weaknesses, and counter-observations - **Selection bias, material:** OpenStack is unusually large, technical, open, and infrastructure-heavy. - **Survivorship bias, moderate:** Successful transformations receive more attention than stalled or abandoned ones. - **Proxy substitution, material:** contribution and merge counts can displace reader task success. - **Appeal to shared developer culture, moderate:** familiar tools may improve status in some teams, but can also subordinate documentation judgment to engineering norms. - **Presentism in tool guidance, now material:** 2017 specifics appear as procedures even though the principles demand continuous maintenance. - **No strong evidence of straw-person argument:** the book gives wikis a fair hearing and admits they may fit small or unusual content. - **Counter-observations in the author's favor:** Gentle rejects one-size-fits-all solutions (P-0019), says community labor is not automatically a cost saving (P-0023), says docs as code cannot guarantee successful API docs (P-0066), names premature publication risk (P-0105), and declines unreliable grammar checks as gates (P-0132). ### Repairs that preserve the argument 1. Replace “docs like code improves quality” with “docs like code makes selected quality controls observable and repeatable.” 2. Replace “same tools create respect” with “shared systems can make work visible; authority, credit, and compensation still require governance.” 3. Replace “keep docs with code” with “place docs where accountable reviewers and synchronized release gates can act.” 4. Replace “automate publishing” with “automate reproducible publication after explicit semantic and release gates.” 5. Replace “measure contributors” with “measure contributor health and representative reader task outcomes together.” --- ## Prompt 8 - systems, context, and later developments ### Context available in 2017 The book sits in the expansion of GitHub-centered open source, static site generators, Read the Docs, Write the Docs, REST APIs, OpenStack, and CI services. It responds to document-control systems based on file locking, office formats, manual builds, separate documentation teams, and PDF sign-off. Its social aim is as important as its tool advice: writers should participate in the same change and review systems as engineers. ### Intellectual and practice lineage ```mermaid flowchart LR L["Literate programming and code-adjacent reference"] --> V["Versioned documentation source"] O["Open-source contribution and peer review"] --> V A["Agile and continuous delivery"] --> B["Automated docs build and release"] V --> DLC["Docs-as-code operating model"] B --> DLC U["User-centered technical communication"] --> DLC DLC --> D["Later convergent practice: Diataxis content types"] DLC --> G["Later platform controls: Actions, environments, protected deployment"] DLC --> X["Current extension: accessibility, supply-chain security, task testing"] ``` Diataxis and current platform controls are **convergent later context**, not claimed causal descendants. ### Current comparison layer - GitHub added HTTPS for Pages custom domains in 2018, overturning P-0038 and P-0109: [GitHub announcement](https://github.blog/news-insights/product-news/github-pages-custom-domains-https/). - GitHub stopped accepting account passwords for Git operations in 2021, so the tutorial's authentication recovery is historical: [GitHub changelog](https://github.blog/changelog/2021-08-12-git-password-authentication-is-shutting-down/). - GitHub supports Pages deployment through Actions with explicit `contents`, `pages`, and identity-token permissions plus an environment: [GitHub Pages workflow documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages). - New repositories commonly use `main`, and GitHub supports configurable default branches: [GitHub default-branch guidance](https://github.com/github/renaming). - OpenAPI 3.2.0 now defines the current specification layer and adds concerns absent from the 2017 survey, including external-resource handling and Markdown/HTML sanitization: [OpenAPI 3.2.0](https://spec.openapis.org/oas/v3.2.0.html). - Diataxis now offers a widely used four-part distinction among tutorials, how-to guides, reference, and explanation: [Diataxis](https://diataxis.fr/). The book already argues that generated reference alone cannot teach onboarding tasks. ### Perspectives present and missing Present: experienced technical writers, editors, developer contributors, OpenStack infrastructure, API documentation, translation operations, and some novice Git users. Missing or thin: disabled users and contributors, low-bandwidth settings, Global South organizations, regulated environments beyond passing mentions, union or labor analysis, maintainers of small non-software documentation, security engineering, and people who tried the method and reverted. --- ## Prompt 9 - DEIB, multicultural, accessibility, and reading-level audit ### Inclusion strengths - Credits three women as author/contributors and names their distinct roles. - Treats technical writers as peers whose work can receive the same contribution credit as code. - Recognizes global asynchronous contribution and translation work. - Warns reviewers that English-language correction can shame contributors. - Allows browser-based entry for learners who are not ready for the command line. - Recommends coaching, waiting for newer reviewers, and letting original authors approve edits to their work. These are useful practices, but few are protected by governance that survives a change in leadership. ### Exclusion and omission risks - Git, terminals, SSH, local runtimes, and public repositories create access and security barriers unrelated to writing skill. - “Fit into the developer ecosystem” can make engineering norms the default authority over reader and editorial needs. - English remains the source language in the dominant example; translation automation does not resolve whose language defines the canonical text. - The book does not test contributor or output workflows with assistive technology. - GitHub contribution graphs privilege visible repository acts and can erase interviews, support work, editing, translation coordination, and community care. - Open participation can shift labor onto unpaid contributors while maintainers retain merge and publication authority. ### Multicultural transferability | Context | Transferability | Adaptation needed | |---|---|---| | Large open-source software project | High | Add current security, access, and sustainability controls | | Small plugin or theme project | Moderate-high | Use a smaller pipeline; avoid OpenStack-scale branching and review roles | | WordPress contributor documentation | High for controls | Support web editing, multilingual review, non-Git entry, and volunteer capacity | | Regulated enterprise docs | Moderate | Add approvals, audit retention, access control, records policy, and validated tooling | | Community knowledge base | Moderate | Preserve low-barrier contribution and nontechnical moderation paths | | Low-bandwidth or mobile-first community | Low-moderate | Provide offline, browser, and asynchronous paths with smaller artifacts | ### Accessibility audit - **Supplied PDF:** untagged according to PDF metadata. Extraction works, but the artifact does not expose a tagged structure tree. Several examples and tables depend on layout. - **Book content:** no systematic treatment of WCAG, keyboard access, focus order, color contrast, captions, alt text, semantic HTML, or screen-reader testing. - **Contributor path:** command-line and Git error handling receive care; assistive-technology compatibility does not. - **Automation:** link, syntax, build, deletion, translation, and whitespace checks appear. Accessibility checks and representative manual audits do not. - **Required modern repair:** add semantic output checks, axe or equivalent automated scans, keyboard review, screen-reader sampling, zoom/reflow checks, alternative text review, and disability-informed task testing. Automated accessibility scans remain non-exhaustive. ### Reading level Syntax is moderate: short sections, concrete examples, tables, and direct commands. Reference density is high: Git, Gerrit, Jekyll, Sphinx, RST, WADL, OpenAPI, CI/CD, DNS, SSH, and OpenStack appear quickly. A reader can parse each sentence and still lack the systems context needed to judge the recommendation. The tutorial lowers vocabulary burden but now increases factual risk because the procedure has aged. ### Supplementary perspectives Use current GitHub and OpenAPI documentation for implementation, Diataxis for content-purpose distinctions, W3C guidance for accessible output, and security guidance for CI permissions, secrets, dependencies, and untrusted contributions. Pair these with studies or local task tests that measure reader success rather than repository activity alone. --- ## Prompt 10 - notes pipeline ### Fleeting notes - A green build is evidence about the pipeline, not the reader's task. - Repository location is a governance decision disguised as file organization. - The book's obsolete tutorial is a live demonstration of documentation drift. - Review checklists need severity, evidence, and override rules or they become ritual. - Contribution graphs count what the platform can see, not all documentation labor. ### Literature notes - **LIT-DLC-01:** Docs as code has four linked controls: source, build, review, and publish. [C-001; P-0018] - **LIT-DLC-02:** Generated API reference cannot replace onboarding, use cases, architecture, examples, and tutorials. [C-007; P-0059] - **LIT-DLC-03:** Preview builds reduce local setup burden and expose output defects. [C-009; P-0104] - **LIT-DLC-04:** Reliable mechanical tests can block; judgment-heavy checks need human review. [C-012; P-0129-P-0132] - **LIT-DLC-05:** Versioning must account for reader state, support policy, archives, redirects, locale, and security retraction. [C-015; P-0142-P-0159] - **LIT-DLC-06:** Contributor and reader measures answer different questions and should not be collapsed. [C-017; P-0191-P-0192] ### Permanent-note candidates #### A documentation build proves reproducibility, not usefulness **Claim:** A successful build shows that a declared source and dependency set can produce an artifact. It does not show that the artifact is accurate, complete, findable, accessible, or usable for a representative task. **Confidence:** High. **Scope and conditions:** Applies where build checks are syntactic, structural, or rendering-focused. Confidence should change if an executable system validates the full task in representative environments and users confirm the result. **Support:** [[Docs Like Code#Prompt 7 - x-ray analysis and fair criticism]]; LIT-DLC-03 and LIT-DLC-04. #### Repository placement allocates documentation authority **Claim:** Putting documentation with code, in a dedicated repository, or in a collaborative editor determines who receives notifications, who can review, which checks apply, and who can publish. File placement is therefore an authority and coordination decision as well as information architecture. **Confidence:** High. **Scope and conditions:** Applies to governed collaborative systems. It does not imply that one repository model is best across products. **Support:** [[Docs Like Code#Prompt 4 - claims, evidence expectations, and dependencies]]; C-005 and C-006. #### Gate strength should follow check reliability and harm **Claim:** A publication check should block only when its result is dependable and the cost of allowing the defect exceeds the cost of a false block. Other checks should warn, collect evidence, or request human judgment. **Confidence:** High. **Scope and conditions:** Safety, legal, and security controls may justify stricter blocking even with some false positives, but they still need ownership and an override process. **Support:** [[Docs Like Code#Prompt 5 - quantitative rigor]]; C-011-C-013. #### Docs-as-code adoption needs an access budget **Claim:** Every new contribution control adds learning, device, account, permission, language, or disability costs. A team should budget support and alternative paths alongside automation work. **Confidence:** Moderate-high. **Scope and conditions:** Costs differ by contributor population and platform. Measure completion and abandonment rather than assuming a Git workflow is either universally open or universally exclusionary. **Support:** [[Docs Like Code#Prompt 9 - DEIB, multicultural, accessibility, and reading-level audit]]. ### Structure-note routing - Link this review to [[3. Resources/MOCs/Book Review Synthesis MOC]]. - Link practice conclusions to [[3. Resources/MOCs/DevRel MOC]] where documentation and developer education overlap. - Do not create a new Documentation MOC from one source; the current vault has no dedicated documentation MOC, and one book does not yet justify it. - Do not create separate permanent-note files in this run because the user's single-file instruction controls. The candidates remain embedded and linkable by heading. ### Attribution audit Paraphrases tied to `P-####` anchors describe the book. Current platform facts link to official sources. C-018, every repair, every posterior, the DEIB audit, the permanent-note wording, experiments, and recommended modern controls are system analysis. Do not attribute them to Gentle. --- ## Prompt 11 - teaching pack ### Audience and learning objectives For technical writers, developer educators, maintainers, documentation leads, and engineers who share responsibility for product documentation. Learners should be able to: 1. Explain the four controls without reducing docs as code to Markdown or Git. 2. Map a documentation change from issue through source, preview, review, tests, publication, and monitoring. 3. Select blocking and advisory checks based on reliability and harm. 4. Separate pipeline metrics from reader outcomes. 5. identify stale implementation advice and verify it against primary sources. 6. Audit the contributor path for access, authority, and maintenance burden. ### Lesson sequence | Lesson | Focus | Activity | Evidence boundary | |---|---|---|---| | 1 | What the model controls | Diagram one current docs change | Model describes controls, not guaranteed outcomes | | 2 | Repository and authority | Map who can propose, approve, publish, revert | Placement does not prove collaboration | | 3 | Build and preview | Compare source diff with rendered artifact | Render success is not task success | | 4 | Review and gates | Classify checks as blocking, advisory, or human | Reliability and harm determine gate strength | | 5 | Reader validation | Run a clean-environment task test | One test does not represent every user | | 6 | Version and release | Design support, redirect, archive, and retraction rules | Policy must match product and legal context | | 7 | Current migration | Replace one obsolete 2017 instruction with a primary-source procedure | Current platform docs can drift again | | 8 | Access and sustainability | Test contributor entry and name owners | Automation creates maintenance obligations | ### Misconception checks - “Markdown in Git means we use docs as code.” **Correction:** source format covers only part of the control system. - “The build passed, so the docs are correct.” **Correction:** inspect the artifact and run the task. - “More contributors mean better docs.” **Correction:** inspect acceptance quality, retention, burden, and reader outcomes. - “Docs must live beside code.” **Correction:** location follows accountable reviewers, release coordination, audience, and access. - “Automation removes human review.” **Correction:** it should remove repeatable mechanical work and focus human judgment. - “The tutorial is safe because the principles are sound.” **Correction:** procedures require versioned verification. ### Case exercise A WordPress plugin changes a REST endpoint. The code PR passes unit tests, but the developer handbook page lives elsewhere and still shows the old schema. Learners must define: the issue link, source location, owner, generated reference boundary, hand-written example, preview, schema and link checks, accessibility check, clean-environment task test, release gate, old-version behavior, and post-release signal. They must also supply a browser-based contribution path for a subject expert who does not use Git locally. ### Assessment Ask learners to produce a one-page control map and defend three gates: one blocking automated check, one advisory check, and one human task review. Passing work names the harm controlled, the evidence produced, the owner, the override path, and the maintenance cost. ### Facilitator cautions - Do not let “like code” make engineering practice the unquestioned standard for writing or community work. - Disclose that the book's empirical support is case-heavy and OpenStack-centered. - Do not attribute the current accessibility, security, or gate-design conclusions to Gentle. - Offer a no-command-line activity path, accessible materials, captions or transcripts, and enough time for unfamiliar Git concepts. - Treat public contribution histories, criticism, and language correction as potential sources of exposure or shame. ### Further reading - [GitHub Pages custom workflows](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages) - [OpenAPI Specification 3.2.0](https://spec.openapis.org/oas/v3.2.0.html) - [Diataxis](https://diataxis.fr/) - [W3C Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG22/) --- ## Prompt 12 - action, PARA, experiments, and drift ### Action inventory #### Take - Record documentation source and output provenance. - Require rendered previews for content changes that affect layout, navigation, code blocks, tables, or generated reference. - Link changes to a reproducible reader problem or explicit acceptance criterion. - Split checks into blocking, advisory, and human-review classes. - Test procedural documentation in a clean, representative environment. - Name owners for build dependencies, security updates, redirects, archives, accessibility, and emergency retraction. #### Consider - Keeping docs beside code when accountable reviewers and synchronized releases benefit. - Generating reference from source while maintaining separate learning and task guidance. - Browser-based or form-based contribution paths that create governed changes behind the scenes. - Versioned output when supported product states materially differ. #### Avoid - Copying any 2017 command, branch, price, IP address, authentication step, or hosting limitation into current instructions. - Treating contribution counts, build passes, or merge speed as reader success. - Blocking useful contributions on subjective style checks. - Assuming public source, free tools, or open pull requests create equitable participation. > [!danger] Most likely misuse > Building an elaborate pipeline, declaring documentation “engineered,” and never testing whether representative readers can finish the task. ### PARA routing | Bucket | Material | Decision | |---|---|---| | Projects | None automatically | Apply only inside a named documentation migration or release project | | Areas | Technical writing, developer education, open-source maintenance | The controls describe recurring responsibility | | Resources | Framework, claim ledger, teaching pack, permanent-note candidates | Reusable reference material | | Archives | This consolidated book review | Completed source analysis belongs here | ### Reversible experiments | Experiment | Claim | Hypothesis | Action | Measure | Duration | Stop condition | Review date | |---|---|---|---|---|---|---|---| | Preview-review comparison | C-009 | Rendered previews reveal defects source review misses | For ten changes, tag defects by source-only or preview-only discovery | Unique defects, review time, severity | 10 changes | Preview cost exceeds findings for five consecutive changes | 2026-10-15 | | Clean-environment task test | C-013 | Representative execution finds semantic gaps automated checks miss | Run one release procedure from a clean environment | Completion, blockers, undocumented assumptions | 4 releases | No unique finding across four representative runs | 2026-12-15 | | Gate calibration | C-012 | Separating blocking and advisory checks reduces false blocks without raising escaped defects | Classify each existing check and record overrides | False blocks, escaped defects, override reason | 8 weeks | Escaped high-severity defects rise | 2026-11-01 | | Access-path test | C-018 | A browser path increases completion without weakening review | Ask representative contributors to use local-Git and browser paths | Completion, abandonment, support requests, accepted quality | 12 attempts | Browser path bypasses required review or exposes sensitive data | 2026-11-15 | ### Decision rules - **Adopt:** repeatable improvement in task completion, severe-defect detection, recovery, or cycle time without disproportionate access cost. - **Adapt:** benefit appears only for certain content, risk levels, or contributor groups. - **Test further:** sample is small, effects conflict, or a new burden appears. - **Reject:** no user or maintenance benefit after representative trials, or harm exceeds the controlled risk. - **Defer:** no owner, representative environment, or safe rollback exists. If the access-path experiment fails, revise “Docs-as-code adoption needs an access budget.” If preview review fails, narrow “A documentation build proves reproducibility, not usefulness” rather than discarding its core distinction. ### Drift monitoring | Area | Source | Frequency | Reassess early when | |---|---|---|---| | GitHub Pages and Actions | Official GitHub docs/changelog | 6 months | Actions, permissions, Pages, or branch policy changes | | Git authentication | Official GitHub authentication docs | 6 months | Token, SSH, passkey, or app policy changes | | OpenAPI | Official specification | 6 months | New minor version or tooling migration | | Accessibility | W3C standards and representative tests | 6 months | Output theme, editor, renderer, or legal requirements change | | Build dependencies | Project lockfiles and security advisories | Each release | Vulnerability, end-of-life runtime, or broken reproducibility | | Reader success | Task tests, support, search, and feedback | Each release | Failure or support burden rises | The four-part framework, the difference between source and rendered output, and the need to distinguish mechanical checks from human judgment will not drift as product facts do. Their local effectiveness can still change with team and product conditions. --- ## Prompt 13 - visual thinking pack ### Book and control map ```mermaid flowchart LR I["Reader problem or product change"] --> S["Versioned source"] S --> B["Reproducible build"] B --> P["Rendered preview"] P --> A["Automated checks"] P --> H["Human technical and editorial review"] A --> G{"Release gates pass?"} H --> G G -->|No| S G -->|Yes| D["Controlled publication"] D --> M["Reader and contributor evidence"] M --> I ``` **Purpose:** Show the complete feedback loop rather than a one-way build pipeline. **Uncertainty:** Causal improvement depends on gate quality, representative review, and response to post-release evidence. **Sources:** C-001, C-004, C-009-C-015; P-0018, P-0104, P-0121-P-0133, P-0142-P-0159. ### Evidence map ```mermaid flowchart TD subgraph Stronger["Stronger support"] D["Direct definitions"] R["Reproducible system properties"] O["Current official drift checks"] end subgraph Limited["Limited support"] C["OpenStack and Rackspace cases"] Q["Contribution and merge counts"] T["Tool comparisons"] end D --> M["Coherent operating model"] R --> M O --> U["Current implementation corrections"] C -. context-bound .-> E["Organizational outcome claims"] Q -. proxy .-> E T -. 2017 snapshot .-> U ``` **Purpose:** Prevent case volume from being read as independent causal evidence. **Sources:** E-01-E-10. Dashed edges mark weak inference. ### Adoption decision tree ```mermaid flowchart TD A["Proposed documentation control"] --> B{"Names a real reader, release, security, or maintenance risk?"} B -->|No| X["Do not add it"] B -->|Yes| C{"Can a deterministic check detect the failure reliably?"} C -->|Yes| D{"Would escape harm exceed false-block cost?"} D -->|Yes| E["Blocking automated gate"] D -->|No| F["Advisory automated check"] C -->|No| G["Human technical, editorial, accessibility, or task review"] E --> H["Assign owner, override, maintenance, and evidence review"] F --> H G --> H ``` **Purpose:** Turn C-011-C-013 and C-018 into an implementation choice. **Uncertainty:** Risk severity and false-positive tolerance are local judgments. ### Excalidraw stakeholder layout Place the reader and contributor in the center. Put writers, subject experts, developers, editors, accessibility reviewers, localization teams, security, release managers, and support in a ring. Put repository permissions, CI runners, preview hosting, production publishing, analytics, and archives in an outer infrastructure ring. Draw solid arrows for approval or publication authority, dotted arrows for feedback, and red warning markers where one role has sole merge, release, or retraction power. Label every handoff with the artifact and decision passed. ### Omitted visuals - **Causal-loop diagram:** omitted because the book does not supply measured relationships strong enough to justify signed causal loops. - **Timeline:** omitted because the review needs only a short 2017-to-2026 drift table, already covered in Prompt 8. - **Terminology map:** omitted because the controlled-vocabulary table is clearer. - **Comparison matrix:** omitted because the wiki/repository and workflow comparisons are context-dependent and would repeat Prompt 3 and Prompt 6. - **Action map:** omitted because the decision tree and experiments already represent the actionable structure. --- ## Session completion check 1. **Prompts run:** 0-13. 2. **Usable outputs:** all 14 prompt sections are present in this consolidated note. 3. **Partial failures or adaptations:** Prompt 0 used the supplied PDF as Layer 1 because no Readwise tool, record, or annotation export was available. Prompt 10 embeds permanent-note candidates rather than creating separate files because the one-file request controls. Prompt 13 omits visuals that would imply unsupported causality or repeat clearer tables. 4. **Missing material:** reader annotations and purpose; stable bibliography; independent outcome studies; current edition or maintained errata; representative accessibility evaluation. 5. **Assumptions:** analytical depth; practical technical-writing, WordPress, developer-education, and open-source use; accessibility and governance emphasis; practitioner-level existing knowledge. 6. **Next prompt:** none. The complete chain is accounted for. 7. **YAML:** `executed_prompts`, `skipped_prompts`, `remaining_prompts`, `next_prompt`, source limits, and status match the file. 8. **Attribution:** author claims, system inference, and current external facts are labeled separately. 9. **Author-claim guard:** C-018, repairs, confidence updates, modern controls, experiments, and permanent-note candidates are not attributed to Gentle. 10. **Corrections:** no prior note existed, so there are no silent revisions. ### Prompts not run None. ### Session record - **Canonical specification:** `/Users/courtneyrobertson/Documents/2nd Brain/6. Templates/Books/Work the Book.md` - **Session date:** 2026-08-22 - **Executed:** 0-13 - **Skipped:** none - **Remaining:** none - **Status:** complete with documented source, reader-emphasis, evidence, and age limits