| name | docs-book-author |
| description | Assemble or extend the printable, textbook-style BigBlueBam manual (the DOCX and PDF offered from /docs). Use when asked to build the downloadable manual, add or refresh a chapter, write chapter intros/callouts/quizzes, or change the book's design. Produces a bold, colorful, per-app book from the SAME content as the web docs, then converts to PDF. |
docs-book-author: design and assemble the BigBlueBam textbook manual
You turn the live web docs into a book someone would happily buy on Amazon to
learn the software: bold, colorful, per-app, genuinely useful. You do NOT rewrite
the instructional content. You layer engagement on top and lay it out with a
designer's eye.
Read first: docs/docs-book-style-guide.md. It is the design system (page,
color, typography, chapter openers, the recurring graphic elements, the quiz
convention, the per-app accent palette, the production pipeline). This skill is
how you execute it. If the two ever disagree, the style guide wins; update it.
The pipeline at a glance
docs/apps/<app>/help.md ──(build-manual.mjs)──▶ site/src/content/manual.generated.json
│ (same text the /docs page renders)
scripts/docs-book/enhancements/<app>.json ◀── you author this layer
▼
node scripts/docs-book/build-book.mjs --app=<app> --pdf
▼
site/public/downloads/BigBlueBam-*.docx ──(LibreOffice)──▶ .pdf
The generator (scripts/docs-book/build-book.mjs) reads the chapter content
verbatim, applies the per-app design system, injects the enhancement layer, and
writes DOCX. With --pdf it converts via headless LibreOffice. --app=<app>
builds one chapter (a sample); no flag builds the full 16-chapter book.
Your job per chapter: author the enhancement file
Each chapter's only authored layer is scripts/docs-book/enhancements/<app>.json.
A chapter still renders without one (default opener, no quiz), but the file is how
it gets its personality. Schema:
{
"app": "bam",
"tagline": "Plan it, drag it, ship it.",
"intro": "2 to 4 sentences...",
"atAGlance": ["3 to 5 short 'best at' bullets"],
"pullQuotes": [
{ "after": "<exact phrase from the chapter>", "text": "<the pull-quote line>" }
],
"callouts": [
{ "after": "<exact phrase>", "type": "tip|important|warning|note|tryit", "text": "<one tight paragraph>" }
],
"quiz": [
{ "type": "mc", "q": "...", "choices": ["...","..."], "answer": "<exact matching choice>", "where": "Section name" },
{ "type": "short", "q": "...", "answer": "...", "where": "Section name" }
]
}
Anchoring rules (this is where it goes wrong)
after is a substring that must appear in the chapter's source text. The
generator collapses whitespace before matching, so a phrase that crosses a
line wrap still matches. Even so, pick a distinctive 6 to 12 word phrase and
copy it from the real text. If a callout does not appear in the output, your
anchor phrase is wrong: grep the chapter for it.- Anchors match paragraph text AND list-item text. Many key facts (defaults,
limits, gotchas) live in the "Key concepts" bullet list; anchor to those.
- Each anchor fires once. Use distinct phrases.
Authoring rules (non-negotiable)
- No em dashes anywhere. Reword. (House rule across all BigBlueBam writing.)
- No invented facts. Intros, callouts, and quizzes describe only what the
source chapter actually says. Tool counts and behavior come from the docs.
- Quiz answers must be findable in the chapter, and every question cites the
section in
where. Mix a couple multiple-choice with a couple short-answer.
Make them about real, useful behavior, not trivia.
- The Introduction chapter (
introduction) has no quiz. It is a suite
overview, not an app lesson. Do not author a quiz (or answer key) for it; the
generator hard-skips the quiz for introduction regardless.
- Agent language is capability, never turnkey or free. "An agent can run a
sprint", never "agents run your sprints" or anything implying agents ship
deployed or free. (See
docs/marketing-voice.md.)
- Callouts: one idea each. Tip = a smarter way. Important = will bite you.
Warning = destructive/irreversible. Note = clarification. Try It = a one-line
exercise the reader can do right now.
- Pull-quotes point at a marquee feature, at most one per major section.
Build and verify
- Author
enhancements/<app>.json.
- Build:
node scripts/docs-book/build-book.mjs --app=<app> --pdf from
scripts/docs-book/.
- Verify the output, do not trust that it generated. Unzip the DOCX and grep
word/document.xml, or read the PDF, and confirm against the definition of
done:
- The opener renders (full-color panel,
CHAPTER N, app name, tagline, intro
card).
- Every callout you authored appears (
grep -o ">TIP<", >NOTE<, >WARNING<,
>TRY IT<). A count of 0 means a broken anchor: fix the phrase.
- Both pull-quotes appear; every screenshot has a
Figure N.M caption.
- The "Check yourself" quiz and "Answer key" are present (except the
Introduction chapter, which has none).
- Zero em dashes:
unzip -p <docx> word/document.xml | grep -c "—" is 0.
- If the PDF step fails, a stale LibreOffice instance (or a self-update) may hold
the single-instance lock. Kill
soffice.exe/soffice.bin, wait a few seconds,
and re-run. The generator already kills-and-retries once.
Full book
node scripts/docs-book/build-book.mjs --pdf builds all 16 chapters in order
(Bam first, then alphabetical) with front matter (title page) and per-chapter
sections. Output: site/public/downloads/BigBlueBam-Manual.{docx,pdf}, the
committed artifacts the /docs download buttons serve. Run it whenever a chapter
or its enhancement file changes, then commit the regenerated artifacts.
Per-app accent palette
bam #2563EB, banter #7C3AED, beacon #059669, bearing #0891B2, bench
#4F46E5, bill #16A34A, blank #9333EA, blast #DC2626, blueprint #0284C7,
board #4338CA, bolt #EA580C, bond #DB2777, book #0D9488, brief #D97706,
bureau #6D28D9, helpdesk #E11D48. (Mirrored in the generator's ACCENT map
and the style guide.)
Hard rules recap
Same content as the web docs, verbatim. No em dashes. No invented facts. Quiz
answers live in the chapter. Capability agent language. Verify the output, never
assume it rendered.
