# A technical book — chapters, code notes and a glossary that stay in step with the software Recipe No. 1, Books and writing. From The know.sh Cookbook: https://know.sh/cookbook/technical-book - For: a developer writing a book about a web framework for a technical publisher - You bring: a signed proposal with its table of contents, a git repository holding the manuscript and the sample app, and the framework’s documentation and changelog - You get: a research library beside the manuscript: a document per chapter, a finding for every concept, scope decision and open question, a glossary that builds itself, and a preview for technical reviewers - Time: an evening to set up, fifteen minutes after each writing session, and an hour each time the framework ships a minor release - Keep it: private while you work; share one document by a read-only link A framework moves faster than a book. You write chapter 7 against version 4.2, and by the time the reviewers see it 4.3 has renamed an option your example depends on. The manuscript and the sample app live in git, where you can diff them. The research that says *why* the chapter reads as it does lives in browser tabs, issue threads and your memory. This recipe gives that research a home, and lets an assistant do the filing. A coding assistant with the know.sh plugin, such as Claude Code, reads your proposal, your manuscript and the framework's documentation, and builds a document per chapter with a finding per concept, each filed as *Evidence* with links to the official docs and changelog. You fix it up in the editor. Because the same assistant can read your sample repository and your library in one session, it can later tell you which of chapter 7's claims still hold against the version you have installed. The index becomes the first draft of the glossary. The manuscript stays in AsciiDoc or Markdown in git, and your publisher's toolchain builds the book. know.sh never sees the build, and the assistant never writes the prose. ## What you will use - **Shelf**: One shelf for the book, say *Larkspur in Practice*, whose line names the framework version the book targets. - **Research document**: One document per chapter; the overview says what a reader can do by the end and which version the chapter was last checked against. - **Finding**: A finding per concept, filed as *Evidence* with its sources; scope choices as *Decision*; open items as *Question*. - **Your AI assistant**: A coding assistant with the know.sh plugin, run inside the book’s repository: it builds the chapter documents from your proposal and manuscript, then checks their claims against the installed code. - **The editor**: Where you correct what the assistant filed, reorder concepts, set types and **Key**, and add the sources it missed. - **The A–Z index**: The glossary: every API name (camelCase identifiers, acronyms, capitalised names) that recurs in finding titles and first lines, with the numbers of the findings that explain it. - **Revisions**: Shows what changed in a chapter’s notes between one release and the next, marked as yours or an assistant’s, and puts back anything a check got wrong. - **Public link**: A read-only preview of a draft chapter for technical reviewers, with a password and an expiry at the end of the review round. ## Method ### 1. Connect a coding assistant in the book’s repository Install the know.sh plugin once, as the terminal below shows, then start `claude` from the root of the repository that holds the manuscript and the sample app, and run `/mcp` to sign in. One session can now read your proposal, your chapters, the lockfile and the installed framework's type definitions, and write to your library. That is the reason to keep the research here rather than in a notes folder: the assistant that can run your tests can also see what you promised the reader. ### 2. Have it build a document per chapter Ask it to read `proposal.md` and each chapter file, then make a shelf named after the book and a document per chapter, "Chapter 7 — Data loading", with a finding per concept the chapter teaches. Each concept is filed as *Evidence*: what the API does in two or three sentences, its signature in a code block, and its sources in order, documentation page first, then the changelog entry, then any design proposal. Scope choices in your proposal become *Decisions*; anything the docs do not settle becomes a *Question*. Tell it to title findings in the framework's own words. The index learns from finding titles and first lines, so `useLoader` reaches it only if it recurs there; plain words such as caching are found with **Look up** (⌘K). ### 3. Fix it up in the editor A dozen chapters come back as a hundred-odd findings in an evening. Read each chapter through and press **Edit**: correct what is wrong, drag concepts into teaching order, and open every source to check it says what the finding claims. A finding with no official source is a claim nobody has checked; change it to *Insight* until it has one. Mark the decisions that constrain other chapters as **Key**, and add a line to each concept such as "Checked against 4.2.0, 2 August." The questions are the list you clear before a draft goes to review. ### 4. Check a chapter against the code When a release lands, or before a chapter goes to review, ask the assistant to check it. It compares each finding with the lockfile and the example under `examples/ch07`, and reports each claim as holds, changed or cannot tell, with the line it checked. Have it file the report as one finding, plus a *Question* for anything it could not settle. It can fix sample code on a branch you review. The prose is yours: read the report, then edit the manuscript yourself, and update the overview with the version you checked. ### 5. Treat the index as the glossary Open the index for the book's shelf and read it as a reviewer would. Each API name leads to the findings that explain it, and plurals get a *See*. Where one finding is the definition, **Highlight** its first sentence; its number turns bold, so the entry points to the right page first. When the publisher asks for the glossary, write it from this list. It holds the API names your chapters rely on; find plain-word concepts with Look up. ### 6. Send a preview to technical reviewers Check your contract first; some publishers restrict early previews. Ask the assistant to copy `ch07-data-loading.adoc` into a separate document, "Early access: Chapter 7", converted to Markdown with a finding per section and your wording untouched. Write its overview yourself in the editor: what reviewers should look for and where to email feedback. Press **Share**, set a password and an expiry at the end of the round, and copy the link, which is shown only once. When the emails arrive, paste them to your assistant and have it file each point on the chapter's research document as a *Bug*, *Problem* or *Suggestion*. ## Prompts to try A coding assistant with the know.sh plugin, such as Claude Code: > Read proposal.md and chapters/ch07-data-loading.adoc. Using know.sh, create a document “Chapter 7 — Data loading” on my Larkspur in Practice shelf with one Evidence finding per concept the chapter teaches: what it does, its signature in a code block, and sources from the official Larkspur documentation and changelog only. File scope choices from the proposal as Decision findings and anything the docs do not settle as Question findings. Do not change the manuscript. A coding assistant with the know.sh plugin, such as Claude Code: > Read the findings in the know.sh document “Chapter 7 — Data loading” and the code under examples/ch07. For each finding, check its claim against the framework version in the lockfile and its installed type definitions. Report each as holds, changed or cannot tell, quoting what you checked. File the report as one Evidence finding called “Drift check” in that document, and a Question finding for each thing you could not settle. Do not edit the manuscript. Your assistant, connected to know.sh (Claude, ChatGPT or a local model): > Using know.sh, search the web for what changed between Larkspur 4.2 and 4.3 that affects route loaders, caching, streaming and form actions. Use only the official release notes, documentation and design proposals, and file what you find as a new document “Larkspur 4.3 changes” on my Larkspur in Practice shelf, one finding per change with the link to where it is announced. Your assistant, connected to know.sh (Claude, ChatGPT or a local model): > Using know.sh, read the reviewer emails I paste below and file each point in the document “Chapter 7 — Data loading” on my Larkspur in Practice shelf: Bug for code that does not run, Problem for a passage that confused them, Suggestion for everything else. Quote the reviewer’s words, put their initials at the start of the title, and do not merge points from different reviewers. ## Variations - Writing a second edition? Put each chapter in **Focus** for its week of revision, run the drift check against the new major version, and let the revisions keep the first edition’s notes. - Plan the production schedule as a campaign, which Claude Code can build with the plugin’s planning tools: an operation set per review round, and each chapter’s drift check *blocking* its review draft. - Not working in a repository? Any assistant connected to know.sh, Claude, ChatGPT or a local model, can file reviewer feedback and research the changelog; only the code check needs one that can read your files. - Writing a textbook meant to be read in the open instead? The [open textbook](/cookbook/open-textbook) recipe shares each chapter from the start. ## Where it falls short - know.sh does not build or export the book. There is no PDF, EPUB, AsciiDoc or Markdown download; the manuscript and its build stay in git and your publisher’s toolchain. - Code blocks are highlighted while you edit, but reading mode and the public link show them as plain text, so reviewers see listings without colour. - Nothing runs code in know.sh. A finding marked as checked means you or your coding assistant ran it in your own repository; know.sh only stores what was found. - Researching changelogs on the web needs an assistant with web search; Claude and ChatGPT have it, many local set-ups do not. Connecting any assistant means signing in once, as the support page describes. ## A note on previews, sources and who wrote what Read your contract before sharing a draft chapter; many publishers set rules on early access. A password and an expiry keep a preview small; they do not stop a reviewer copying what they read. Reviewers read the link but cannot write in it, so their feedback comes by email. Quote official documentation briefly and link to it rather than copying pages. Assistants make mistakes, drift checks included: treat everything yours files as a first draft, and read the code it cites before you change a sentence. The prose is yours. If an assistant generates text that goes into the book, tell your publisher and follow their policy; Amazon KDP, for self-published editions, asks you to disclose AI-generated text but not AI help with checking and editing. Text an AI writes on its own may not be protected by copyright. Indexed under: Technical books, Sample code, API drift, Glossaries, Technical review, Early access, Changelogs.