Contributing to Books¶

This tutorial explains how to contribute chapters, sections, examples, and fixes to the existing FCC 3-book series. Whether you have found a gap, identified an error, or want to write an entire new chapter, this guide walks through the full contribution lifecycle from opportunity identification to merged PR.

The 3-book series is a community asset. High-quality contributions are gratefully accepted and credited. The process below prioritizes quality and consistency while keeping contribution friction as low as possible.

The 3 Existing Books¶

Before contributing, familiarize yourself with the three books and their scopes.

Book 1: Understanding FCC (Beginner)¶

Scope: First-principles introduction to FCC, R.I.S.C.E.A.R., workflow graphs, governance, and collaboration. 8 chapters, ~2-3 hours reading.

Good contribution opportunities: - Additional worked examples for abstract concepts - Beginner-friendly diagrams - Glossary entries - Common-mistakes callouts

Book 2: Building with FCC (Intermediate)¶

Scope: Practical application: project setup, custom personas, workflow graphs, plugins, event bus, collaboration sessions, CI/CD. 8 chapters, ~3-4 hours reading.

Good contribution opportunities: - Plugin recipes - Workflow graph patterns from real projects - CI/CD integration cookbooks - Troubleshooting guides

Book 3: Advanced FCC (Advanced)¶

Scope: Semantic search, knowledge graphs, RAG, federation, protocol integration, cross-project orchestration, enterprise deployment. 8 chapters, ~4-5 hours reading.

Good contribution opportunities: - Case studies from production deployments - Performance benchmarks and tuning guides - Protocol implementation walkthroughs - Federation topology patterns

See The FCC Framework Series for the full reading path.

Contribution Types¶

You can contribute at four levels of scope:

Type	Effort	Review Depth	Examples
Fix	15-60 min	Light	Typos, broken links, clarification
Enhancement	1-4 hours	Moderate	New example, improved diagram, expanded section
Section	4-16 hours	Full	New section within an existing chapter
Chapter	20-80 hours	Full + editorial	New chapter added to a book

Finding Opportunities¶

Gap Analysis¶

Read the books looking for:

Concepts introduced but under-explained -- add examples or a callout
Forward references to missing content -- fill the gap
Outdated information -- update against current FCC version
Missing diagrams -- where prose describes structure, a diagram may help

Issue Tracker¶

Check open issues tagged books or documentation:

gh issue list --label books --state open

Feedback Archives¶

Review closed reader-feedback issues. Patterns of confusion indicate content gaps.

Your Own Experience¶

If you stumbled on something while reading, others will too. Your stumble is an opportunity.

Proposal Process¶

For fixes and enhancements, skip the proposal and open a PR directly.

For sections and chapters, open a proposal issue first.

Proposal Issue Template¶

## Proposal: {Chapter or Section Title}

**Target book:** Book 1 / Book 2 / Book 3
**Target location:** {existing chapter or new chapter position}
**Scope:** section / chapter
**Estimated word count:** {n}

### Why This Is Needed
{1-2 paragraphs on the gap this fills}

### Outline
- Learning objectives (3-5)
- Sections (5-8 for a chapter, 2-4 for a section)
- Examples (list)
- Diagrams (list)

### My Experience
{why you are qualified to write this}

### Timeline
{estimated weeks to first draft}

Review Criteria¶

Maintainers evaluate proposals on:

Fit -- does it match the book's scope and level?
Uniqueness -- does it duplicate existing content?
Clarity -- is the outline concrete and actionable?
Capacity -- can the author reasonably deliver the scope?

Most proposals get feedback within 7 days. Approved proposals receive a target chapter position and a branch name.

Chapter Template Structure¶

Every chapter in the series follows a standard structure. New chapters must conform.

---
title: "Chapter N: {Title}"
subtitle: "{Subtitle, optional}"
level: beginner|intermediate|advanced
estimated_time: "{X minutes}"
prerequisites:
  - "Chapter N-1"
  - "Familiarity with {concept}"
learning_objectives:
  - "Explain..."
  - "Apply..."
  - "Design..."
---

# Chapter N: {Title}

{Opening paragraph: 2-3 sentences stating what this chapter does and why}

---

## Section 1: {Name}

{Section content with prose, examples, diagrams}

### Sub-section (h3, use sparingly)

---

## Section 2: {Name}

{...}

---

## Worked Example: {Name}

{Complete example demonstrating chapter concepts}

---

## Summary

- Bullet list of key takeaways (3-5)

## Exercises

1. {Exercise 1}
2. {Exercise 2}
3. {Exercise 3}

## Further Reading

- [Cross-reference](../path.md) -- why relevant

Style Rules¶

Every chapter must follow these rules:

Chapter style rules

Voice: first-person plural ("we"), active voice
Paragraph length: 3-5 sentences
Sentence length: under 35 words typical
Code examples: executable as-is, language-tagged
Diagrams: Mermaid, FCC color conventions
Jargon: defined on first use
No h4 or deeper: restructure instead

Review Workflow Using the Documentation Evangelist¶

Contributions go through a 3-stage review. The Documentation Evangelist (DE) persona guides the process.

Stage 1: Self-Review (contributor)¶

Before opening the PR, run through a self-review checklist:

Stage 2: DE Review (maintainer)¶

A maintainer acting as DE reviews:

Voice and style alignment with prior chapters
Structural coherence
Audience-level appropriateness
Cross-reference integration

Typical turnaround: 3-7 days for a full chapter.

Stage 3: BV Review (technical)¶

A subject-matter expert acting as Blueprint Validator (BV) reviews:

Technical accuracy
Code example correctness
Claim-evidence alignment
Concept completeness

Typical turnaround: 3-7 days.

Review Flow¶

flowchart LR
    Draft[Draft PR] --> Self[Self-Review]
    Self --> Open[Open PR]
    Open --> DE[DE Review<br/>style + voice]
    DE -->|changes| Revise1[Revise]
    Revise1 --> DE
    DE -->|approve| BV[BV Review<br/>technical]
    BV -->|changes| Revise2[Revise]
    Revise2 --> BV
    BV -->|approve| Merge[Merge]

    classDef stage fill:#c8e6c9,stroke:#2e7d32;
    classDef review fill:#fff3e0,stroke:#e65100;
    classDef revise fill:#ffebee,stroke:#b71c1c;
    class Draft,Self,Open,Merge stage;
    class DE,BV review;
    class Revise1,Revise2 revise;

Style Guide Alignment¶

The series style guide lives at docs/books/STYLE_GUIDE.md (if present). Key provisions:

Voice and Person¶

Person: first-person plural ("we")
Voice: active where possible, passive only when the actor is truly irrelevant
Tense: present for instructions and explanations; past for historical context

Terminology Consistency¶

The series uses canonical terminology for key concepts:

Use This	Not This
persona	agent, role, actor
workflow graph	pipeline, DAG, graph
stage	step, phase (in workflow context)
archetype	persona type, category
scenario	use case, case
simulation	run, execution

Code Examples¶

Python 3.10+ syntax
Import from fcc.api where possible
All examples executable
Comments explain why, not what

# Good example: comment explains intent
from fcc.api import PersonaRegistry

# Load the shipped defaults; teams override with load_from_dir()
registry = PersonaRegistry.load_default()

Diagrams¶

All diagrams use Mermaid with FCC color conventions:

flowchart LR
    A[Core persona] --> B[Integration persona]
    B --> C[Outcome]

    classDef core fill:#fff3e0,stroke:#e65100,stroke-width:2px;
    classDef integration fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    classDef outcome fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    class A core;
    class B integration;
    class C outcome;

Headings¶

h1: chapter title (one per chapter)
h2: sections
h3: sub-sections (use sparingly)
h4+: do not use; restructure instead

Build Verification Before PR¶

Always verify your contribution builds before opening a PR.

Local Preview¶

# Using MkDocs
mkdocs serve

# Using Quarto
quarto preview

Open the preview, navigate to your new/changed content, verify:

Content renders correctly
Diagrams render
Code blocks have syntax highlighting
Cross-links resolve
Navigation menu updates

Link Validation¶

# Run the FCC docs validator
fcc validate-docs

This checks cross-reference health across the entire docs set.

Code Example Validation¶

If your chapter includes Python code examples:

# Extract and run examples from the chapter
python -m fcc.scaffold.example_runner docs/books/book2_building_with_fcc/chapters/ch05.md

Every example must exit 0.

Example Successful Contribution¶

Here is a summary of a hypothetical merged contribution:

Proposal Issue¶

Proposal: Section on Plugin Error Handling (Book 2, Chapter 5)

Target: Book 2, Chapter 5 (Plugin Development) Scope: Section (est 1200 words)

While writing a plugin at my company, I found Chapter 5 covers the happy path but says nothing about error handling. This section fills that gap.

Outline¶

Learning objective: "Design plugin error handling that surfaces failures without crashing the host"
4 sections: Error Categories, Graceful Degradation, Propagation Patterns, Observability
2 code examples: error classifier, retry decorator
1 diagram: error flow through plugin boundaries

PR¶

Branch: book2-ch5-plugin-error-handling
1 file changed: docs/books/book2_building_with_fcc/chapters/ch05-plugins.md
+180 lines

Review¶

Day 1: PR opened
Day 2: DE review, 4 style comments, contributor addresses
Day 4: BV review, 2 technical comments, contributor addresses
Day 5: Both approve, merged

Total time from proposal to merge: 18 days (with contributor responsive within 24h).

Getting Credit¶

Contributors are credited in three places:

Git history -- your commits are the primary record
Chapter front matter -- the contributors field lists authors
Book credits page -- cumulative list across the book

---
title: "Chapter 5: Plugin Development"
contributors:
  - name: "Original Author"
  - name: "Your Name"
    contribution: "Error handling section"
---

Common Rejection Reasons¶

Why PRs get rejected

Out of scope -- content belongs in a tutorial, blog post, or ADR, not a book chapter
Duplicates existing content -- the topic is already covered elsewhere in the series
Wrong book -- intermediate content proposed for the beginner book
Broken examples -- code that does not execute
Style drift -- contributor's voice differs sharply from book's voice
Insufficient review response -- contributor disengages during review

Most rejections lead to a revised resubmission. Rejection is not permanent.

Quick Contribution Checklist¶

Next Steps¶

Building Your Own Book -- if you want to create a new book instead
Publications Workflow Prompts -- prompts for drafting and reviewing
The FCC Framework Series -- the 3 existing books
Documentation Evangelist Persona -- DE deep dive
Blueprint Validator Persona -- BV deep dive
Community Guidelines -- contribution conduct and norms