title: Content Style Guide last_updated: 2026-03-21

Content Style Guide

Standards for writing content in the Agentic Developer's Playbook.

Voice and Tone

  • Second person — always address the reader as "you"
  • Direct and practical — lead with what to do, then explain why
  • Honest — document limitations, costs, and failure modes alongside successes
  • Opinionated — recommend specific approaches rather than listing all options equally

Structure

Curriculum Modules

Each module follows the dual-layer structure:

  • concepts.md — tool-agnostic principles (~1500 words max)

    • Opens with the core question the module answers
    • Explains the mental model or principle
    • Includes diagrams for non-trivial concepts
    • Ends with key takeaways (3-5 bullet points)

  • {tool}.md — tool-specific implementation

    • Opens with prerequisites (tool version, setup needed)
    • Step-by-step instructions with copy-paste-ready commands
    • Screenshots or output examples where helpful
    • "Adapt this by..." notes on every code block

  • exercises.md — hands-on practice

    • 3-5 exercises per module, increasing in difficulty
    • Each exercise has: objective, steps, expected outcome, hints
    • At least one exercise uses the reader's own project, not a toy example

Reference Entries

  • Use the appropriate template from the same directory
  • Every pattern has "When to Use" and "When NOT to Use" sections
  • Every anti-pattern explains "Why Developers Do This" (empathy before correction)
  • Include token cost estimates for expensive workflows

Formatting

Headings

  • H1 (#) — document title only (one per file)
  • H2 (##) — major sections
  • H3 (###) — subsections
  • Don't skip heading levels

Code Blocks

  • Always specify the language for syntax highlighting
  • Every code block must be copy-paste ready
  • Add # Adapt this by: ... comments for parts the reader should customize
  • For multi-step procedures, use separate code blocks (not one giant block)
  • Internal links: always use relative paths (../reference/patterns/fan-out-fan-in.md)
  • External links: use descriptive text, not raw URLs
  • Link to GLOSSARY.md on first use of a term within a document

Tables

  • Use for comparisons, feature matrices, and structured data
  • Keep tables under 6 columns — wider tables are hard to read
  • Left-align text columns, center-align status/boolean columns

Admonitions

Use blockquotes with bold prefixes for callouts:

Note: Additional context that's helpful but not critical.

Warning: Something that could cause problems if ignored.

Cost: Token cost information for the described workflow.

YAML Frontmatter

Required on every content file:

---
title: Document Title
tested_with:           # omit for tool-agnostic content
  claude-code: "1.0.x"
  codex-cli: "0.2.x"
last_updated: 2026-03-21
status: experimental   # experimental | proven | battle-tested
difficulty: beginner   # beginner | intermediate | advanced
prerequisites: []      # module IDs, e.g., [02-project-memory]
---

Terminology

  • Use terms as defined in GLOSSARY.md
  • Define new terms on first use with a brief inline definition
  • Add significant new terms to the glossary via PR
  • Avoid jargon that isn't in the glossary — if you need it, add it