# Beta Reader Protocol Status: ready to run after the editorial branch is merged or shared as a review branch Version under review: PostgreSQL 18 edition Canonical source: `Manuscript/` ## Purpose The beta is not a final proofread. It tests three different promises: 1. Primary readers can build a physical and operational model of PostgreSQL without already being database specialists. 2. PostgreSQL experts can trust the literal mechanism beneath the metaphors. 3. A reader can start the companion environment, complete the core labs, and recover from mistakes without undocumented help. Do not combine these audiences into one undifferentiated score. A passage can be delightful to a primary reader and still be technically unsafe; it can also be impeccable to an expert and exhausting to the intended audience. ## Cohorts Recruit 8–12 readers in each cohort. A useful minimum viable beta is five completed readers per cohort, but publication confidence should be marked lower when a cohort falls below eight. ### A. Primary audience Backend or application engineers who: - can write joins, aggregates, and basic DDL; - have used PostgreSQL in an application; - do not already identify as PostgreSQL internals or performance experts. Primary question: does the book create durable capability without turning into a reference manual on the main road? ### B. Expert red-team Include a mix of PostgreSQL DBAs, performance engineers, contributors, extension authors, and production operators. Ensure that the cohort contains at least: - one storage/MVCC/WAL reviewer; - one planner/executor reviewer; - one HA/replication reviewer; - one security/RLS reviewer. Primary question: does any vivid simplification teach a false operational model? ### C. Teaching and usability Self-directed learners, technical educators, workshop authors, or documentation specialists. Primary question: can a reader predict, observe, explain, repair, and generalize without hidden setup knowledge or prematurely revealed answers? ## Review package Give every participant the same package: - the exact branch or immutable commit under review; - `Manuscript/00 - Introduction/Index.md` as the entry point; - the PostgreSQL 18 version contract and environment verification command; - the chapter assignment and expected completion date; - this protocol and the feedback template below; - a private channel for security-sensitive or potentially embarrassing technical defects. Do not silently update the review branch while a cohort is reading it. If a P0 correction must land, record the old and new commit and tell affected readers which version they used. ## Chapter assignment strategy Every chapter needs at least: - three primary-audience completions; - two expert completions in the relevant subsystem; - two setup/usability completions for any chapter containing core labs. Oversample the highest-risk chapters: | Chapter | Extra review needed | | --- | --- | | 2 — Physical Storage & MVCC | storage/MVCC expert and primary-reader metaphor recall | | 4 — Query Planning & Execution | planner expert and pacing/drop-off observation | | 5 — Durability & Transactions | WAL/recovery expert and two-session lab verification | | 6 — Resource Management & Processes | process/memory/cache expert | | 7 — Wait Events & Concurrency | production diagnostician and optional-tool usability | | 8 — Scaling & Architectural Coordination | HA/replication reviewer and vendor-claim audit | | 9 — Identity & Access Control | PostgreSQL security/RLS reviewer | | 10 — Summary & Epilogue | readers who completed at least four earlier chapters | ## Per-chapter feedback form Collect these answers immediately after each assigned chapter: 1. Reader cohort and relevant experience. 2. Commit reviewed. 3. Chapter and time spent. 4. Capability gain, 1–7: “How much more capable do you feel after this chapter?” 5. First confusion: “What was the first point where your mental model became uncertain?” 6. Trust break: “Did any sentence make you doubt the book's technical authority? Quote or link it.” 7. Removal: “What would you delete, shorten, or move to the field guide?” 8. Lab result: completed without help / completed with help / could not complete / no core lab. 9. Undocumented prerequisite, if any. 10. Prediction quality: “Before the explanation, could you make a falsifiable prediction?” 11. Transfer: “Name one unfamiliar PostgreSQL situation you can now reason about.” 12. Metaphor boundary: “Which metaphor was most useful, and where could it mislead?” 13. Defects with file path, heading, quoted phrase, expected model, and evidence. ## End-of-book feedback form Ask only readers who completed the agreed route: 1. Recommendation score, 0–10. 2. “What single thing prevents you from giving this book a 10?” 3. “Describe PostgreSQL's central design tendency one week after finishing, without reopening the book.” 4. “Walk through a read from connection to returned rows.” 5. “Walk through a write from statement to commit acknowledgement and crash recovery.” 6. “A query is slow. What evidence distinguishes working, waiting, and blocking?” 7. “Which chapter felt most like a manual rather than a narrative, and where did that shift begin?” 8. “Which idea will change something you do at work?” 9. “Who is this book not for?” ## Defect severity and triage ### P0 — stop-the-line Use P0 when feedback identifies: - a false production mechanism; - unsafe operational or security advice; - a contradiction in MVCC, WAL, process, cache, replication, or visibility models; - a core lab that fails from the declared clean PostgreSQL 18 environment; - a version or vendor claim presented as universal when it is not. Pause new review assignments for the affected material. Reproduce the issue, cite a primary source, correct the literal model, scan for duplicates, add a regression check where possible, and notify readers who saw the old text. ### P1 — trust, learning, or reproducibility blocker Examples: misleading boundary, obsolete non-core behavior, an optional tool that looks mandatory, serious pacing friction, or an undocumented prerequisite. P1 issues must be resolved or explicitly accepted with a publication-impact note before release. ### P2 — polish Examples: repetition, navigation, terminology, typo, awkward transition, or optional elaboration. Batch these after P0/P1 decisions so the team does not polish text that will move or disappear. ## Weekly synthesis Maintain one row per finding with: | Field | Meaning | | --- | --- | | ID | stable `BETA-###` identifier | | Cohort | primary / expert / teaching | | Source | reader and review commit | | Location | canonical Markdown file and heading | | Severity | P0 / P1 / P2 | | Observation | what the reader experienced or disputed | | Evidence | lab output, primary source, or repeated-reader pattern | | Decision | fix / move / clarify / accept / defer | | Owner | person responsible for resolution | | Regression guard | test, validator rule, or explicit reason none is possible | | Status | open / verifying / closed | Summarize patterns by cohort. Three independent readers stumbling at the same transition is a structural signal even when no sentence is factually wrong. ## Release decision The Markdown edition is ready for publication authoring only when: - no known P0 issue remains; - all core PostgreSQL 18 lab checks pass from a clean checkout; - expert disagreement concerns nuance or editorial choice rather than basic mechanics; - Chapters 4 and 7 do not produce a recurring narrative-to-manual drop-off; - primary readers can reconstruct the central mental model a week later; - at least one security reviewer accepts the Chapter 9 threat boundaries; - at least one HA reviewer accepts the Chapter 8 failure and replication boundaries; - the most common answer to “what prevents a 10?” is polish or desired additional scope, not trust or reproducibility. Record the final decision as **release**, **release with named follow-ups**, or **hold**. Include the reviewed commit, cohort completion counts, all accepted P1 risks, and the exact PostgreSQL/extension/vendor version contract.