Building Your Own Book¶

This tutorial walks you through creating a custom technical book using the FCC Agent Team Framework's publishing pipeline. By the end, you will have a plan, a persona team, a chapter outline, a drafting workflow, a review cycle, and a built PDF/EPUB/DOCX. The tutorial includes a complete worked example based on a fictional book "Shipping Event-Driven Systems."

FCC is designed to help small teams and individuals produce technical books with the rigor of a formal publishing process: persona-driven drafting, structural critique, consistent voice, and automated builds. You do not need a publisher or a 200-person team to use this pipeline.

Who This Tutorial Is For¶

Audience

Engineers and architects who want to publish what they know
Technical leads creating internal onboarding books
Open-source maintainers producing canonical project books
Researchers publishing applied-methods guides
Teams capturing institutional knowledge before it disperses

Expect to invest 40-120 hours for a first book, depending on scope. Most solo authors complete a 10-chapter book in 3-6 months working part-time.

Prerequisites¶

FCC installed (pip install -e . from the repo root)
Quarto installed (optional, for PDF/EPUB generation): https://quarto.org/docs/get-started/
Familiarity with Markdown and YAML
A topic you know well enough to teach

Step 1: Plan Your Book's Scope and Audience¶

Before writing a single paragraph, answer these questions in a one-page plan:

Scope Questions¶

What is the single thesis? State it in one sentence.
Who will read it? Describe two reader personas.
What will readers be able to do after finishing? List 3-5 outcomes.
What is out of scope? List 3-5 topics you will NOT cover.
How long? Word count and chapter count targets.

Audience Modeling¶

Use the User Advocate Architect (UAA) persona to model your audience:

You are the User Advocate Architect. Model two reader personas for a book
titled "Shipping Event-Driven Systems" targeting backend engineers with
2-5 years of experience.

For each persona, produce:
- Name and role
- Prior knowledge
- Goals for reading the book
- Concerns they bring
- Success criteria (how they know the book helped)

Worked Example¶

For "Shipping Event-Driven Systems":

Thesis: Event-driven systems are operationally manageable when designers apply four disciplines: explicit contracts, idempotency, replayable state, and observable flow.
Audience: Backend engineers at Startup-to-Growth stage companies.
Outcomes: (1) Design event contracts that survive schema evolution. (2) Build idempotent consumers. (3) Debug production event flows. (4) Replay state from event logs. (5) Instrument event systems for observability.
Out of scope: stream processing theory, specific vendor internals, Kafka/Kinesis tuning guides.
Length: 10 chapters, ~60,000 words.

Step 2: Design Your Persona Team with R.I.S.C.E.A.R.¶

Your book needs a persona team to draft, review, and iterate. The minimal team is 4-5 personas. Design each using the 10-component R.I.S.C.E.A.R. specification.

Minimal Book Team¶

Persona	Role in Book Production
Research Crafter (RC)	Source gathering, prior art
Blueprint Crafter (BC)	Chapter outlines, narrative arc
Documentation Evangelist (DE)	Drafting, voice, style
Blueprint Validator (BV)	Technical and structural review
User Advocate Architect (UAA)	Audience alignment

Customizing Personas for Your Book¶

Each persona's constitution should adapt to your book's voice and standards. For example, DE's style component might be customized to:

style:
  tone: "conversational but precise"
  voice: "first-person plural ('we'), active voice"
  paragraph_length: "3-5 sentences"
  code_example_policy: "every concept demonstrated within 2 paragraphs"
  jargon_policy: "defined on first use, glossary entry required"

Store customizations in a book-personas/ directory at your book's root.

Step 3: Outline Chapters with the Blueprint Crafter¶

Run the Chapter Outline Authoring prompt for each chapter. The BC persona produces a structured outline per chapter.

Outline YAML Format¶

chapter: 3
title: "Designing Event Contracts"
learning_objectives:
  - "Explain why event contracts differ from API contracts"
  - "Apply schema evolution patterns to event payloads"
  - "Design event metadata for cross-team use"
prerequisites:
  - Chapter 1 (event fundamentals)
  - Chapter 2 (publish-subscribe patterns)
sections:
  - name: "The Contract Asymmetry"
    summary: "Why events bind more tightly than APIs"
    est_words: 400
  - name: "Schema Evolution Patterns"
    summary: "Adding fields, deprecating fields, versioning"
    est_words: 1200
  - name: "Metadata Conventions"
    summary: "Tracing, causation, ownership fields"
    est_words: 800
  - name: "Worked Example: Payment Event"
    summary: "End-to-end contract with evolution"
    est_words: 1000
diagrams:
  - placement: "Section 1"
    type: "comparison"
    subject: "API vs event coupling"
  - placement: "Section 2"
    type: "sequence"
    subject: "backwards-compatible schema change"
exercises:
  - "Design a v2 event for [scenario]"
  - "Identify breaking vs non-breaking changes in [sample diff]"
est_total_words: 3500

Planning Across Chapters¶

Ensure your chapters flow with dependency tracking:

flowchart TD
    Ch1[Ch 1: Fundamentals] --> Ch2[Ch 2: Pub-Sub Patterns]
    Ch2 --> Ch3[Ch 3: Event Contracts]
    Ch3 --> Ch4[Ch 4: Idempotency]
    Ch4 --> Ch5[Ch 5: Consumer Patterns]
    Ch3 --> Ch6[Ch 6: Replay & State]
    Ch5 --> Ch7[Ch 7: Observability]
    Ch6 --> Ch7
    Ch7 --> Ch8[Ch 8: Failure Modes]
    Ch8 --> Ch9[Ch 9: Operations]
    Ch9 --> Ch10[Ch 10: Case Studies]

    classDef ch fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    class Ch1,Ch2,Ch3,Ch4,Ch5,Ch6,Ch7,Ch8,Ch9,Ch10 ch;

Step 4: Draft Chapters with the Research Crafter and DE¶

For each chapter, follow this drafting cycle:

4a. Research (RC)¶

Gather source material: - Prior chapters for cross-reference - Code examples you will include - External papers, blog posts, specs - Personal war stories with permission

Produce a research brief: 400-word summary with citations.

4b. Draft (DE)¶

Follow the outline produced by BC. Key drafting disciplines:

Drafting disciplines

Write in 500-word chunks; rest between chunks
Draft concepts before examples, examples before exercises
Use the Drafting a New Chapter prompt as your workflow spine
Commit drafts to git daily; version chapters independently

4c. Generate Diagrams¶

Use the Generating Diagrams prompt. Save each diagram as a separate Mermaid file in diagrams/ and include via Quarto short-codes.

Step 5: Review Cycles with the Blueprint Validator¶

After a chapter drafts, run two review passes.

Pass 1: Technical and Structural (BV)¶

Use the Reviewing an Existing Chapter prompt. BV scores the chapter on:

Technical accuracy
Claim-evidence alignment
Code example correctness
Cross-reference health
Logical coherence

Pass 2: Style and Voice (DE)¶

DE does a second pass focused on:

Voice consistency with prior chapters
Jargon handling
Paragraph length
Transition quality

Pass 3: Audience Fit (UAA, optional)¶

UAA spot-checks a sample: would your target audience understand this chapter?

Review Artifact¶

Produce a review record per chapter:

## Review: Chapter 3 "Designing Event Contracts"
**Draft date:** 2026-03-15
**Reviewer:** BV + DE
**Overall score:** 4/5
**Blockers:** 2 (see findings below)
**Nice-to-haves:** 5

### Blockers
1. Line 245: code example uses deprecated API (fix: update to v2 API)
2. Section 3: claim about "99% of teams" lacks citation (fix: remove or cite)

### Nice-to-haves
(5 items)

### Status
Revision required. Target re-review: 2026-03-22.

Step 6: Quarto Configuration¶

Quarto is the recommended build tool for producing PDF, EPUB, and DOCX from a Markdown book. If you are not using Quarto, you can stop after Step 5 -- your Markdown is the deliverable.

Project Structure¶

my-book/
  _quarto.yml
  index.qmd
  chapters/
    01-fundamentals.qmd
    02-pubsub.qmd
    03-contracts.qmd
    ...
  diagrams/
    contract-evolution.mmd
  book-personas/
    rc.yaml
    bc.yaml
    de.yaml
    bv.yaml
  code/
    examples/
  references.bib

Sample `_quarto.yml`¶

project:
  type: book

book:
  title: "Shipping Event-Driven Systems"
  author: "Your Name"
  date: "2026"
  chapters:
    - index.qmd
    - chapters/01-fundamentals.qmd
    - chapters/02-pubsub.qmd
    - chapters/03-contracts.qmd
    - chapters/04-idempotency.qmd
    - chapters/05-consumer-patterns.qmd
    - chapters/06-replay-state.qmd
    - chapters/07-observability.qmd
    - chapters/08-failure-modes.qmd
    - chapters/09-operations.qmd
    - chapters/10-case-studies.qmd
  appendices:
    - chapters/glossary.qmd
    - chapters/references.qmd

format:
  html:
    theme: cosmo
    code-fold: false
    toc: true
  pdf:
    documentclass: scrbook
    geometry:
      - margin=1in
  epub:
    cover-image: cover.png

bibliography: references.bib

Build Commands¶

# Preview locally
quarto preview

# Build all formats
quarto render

# Build PDF only
quarto render --to pdf

# Build EPUB only
quarto render --to epub

Step 7: Iterate Based on Reader Feedback¶

Publish a draft, gather feedback, iterate. Do not wait for perfection.

Feedback Collection¶

Set up three channels:

GitHub issues -- structured feedback from engineers
Anonymous survey -- one per chapter with 3 questions
Direct interviews -- 5 readers at draft and 10 at final

Survey Questions (per chapter)¶

What is one concept you will use within 30 days?
What confused you?
What is missing?

Iteration Workflow¶

Run the Publication Retrospective prompt 30 and 90 days after release. Bucket feedback by chapter and severity. Apply changes in a v1.1 release.

Worked Example: First 30 Days¶

Here is a concrete day-by-day plan for the first month of "Shipping Event-Driven Systems":

Day	Activity	Persona
1-2	Write plan, pick audience	UAA
3-5	Customize persona constitutions	BC
6-8	Outline chapters 1-3	BC
9-10	Research for chapter 1	RC
11-15	Draft chapter 1	DE
16-17	Review chapter 1	BV + DE
18-19	Revise chapter 1	DE
20-21	Research for chapter 2	RC
22-26	Draft chapter 2	DE
27-28	Review chapter 2	BV + DE
29-30	Revise chapter 2, retro	CO

At this pace, a 10-chapter book takes 4-5 months.

Common Pitfalls¶

Book writing pitfalls

Writing without outlining -- produces rework. Outline first.

Skipping reviews -- solo authors especially need BV's structural critique.

Waiting to ship -- drafts published early get 10x more feedback.

Persona drift -- customize persona constitutions upfront, freeze during drafting.

Ignoring audience fit -- write for a specific reader, not "everyone."

Over-scoping -- if your ToC exceeds 15 chapters, cut it in half.

Perfectionism -- ship a v1.0 at 80% polish; iterate to 95% in v1.1.

Build Checklist¶

Before you declare v1.0:

Next Steps¶

Contributing to Books -- contribute to the existing 3-book series
Publications Workflow Prompts -- all drafting/review prompts
R.I.S.C.E.A.R. Specification -- persona design
Documentation Evangelist Persona -- DE deep dive
Blueprint Validator Persona -- BV deep dive
The FCC Framework Series -- the 3 existing books as exemplars