mdbook-tech-writer

# mdBook Technical Writer Write professional technical documentation for software projects using mdBook. This skill covers the full lifecycle: planning, structuring, writing, reviewing, and maintaining docs. ## Before Starting 1. Read `references/mdbook-structure.md` for mdBook conventions, `book.toml` config, and `SUMMARY.md` patterns. 2. Read `references/writing-style.md` for technical writing rules and Rust ecosystem conventions. 3. Use templates from `templates/` as starting points for different chapter types. ## Workflow ### Phase 1: Audit & Plan Assess the project before writing: 1. **Scan the codebase** — identify public APIs, key modules, entry points, configuration, and CLI commands. 2. **Identify audience segments** — developers using the library, operators deploying it, contributors. 3. **Map existing docs** — check for README, inline doc comments (`///`), existing markdown files. 4. **Create a documentation plan** — list chapters needed, assign priority (P0 = blocks adoption, P1 = important, P2 = nice to have). Output: a `docs-plan.md` with audience matrix and chapter list. ### Phase 2: Structure the Book Create the mdBook project structure: ``` docs/ ├── book.toml ├── src/ │ ├── SUMMARY.md │ ├── introduction.md │ ├── getting-started/ │ │ ├── installation.md │ │ ├── quick-start.md │ │ └── configuration.md │ ├── guides/ │ │ ├── basic-usage.md │ │ └── advanced-usage.md │ ├── architecture/ │ │ ├── overview.md │ │ ├── design-decisions.md │ │ └── internals.md │ ├── api-reference/ │ │ └── (module-per-file) │ ├── operations/ │ │ ├── deployment.md │ │ ├── monitoring.md │ │ └── troubleshooting.md │ ├── contributing.md │ └── changelog.md └── theme/ (optional customizations) ``` Rules for `SUMMARY.md`: - Group chapters into logical parts using `# Part Title` - Use indentation for sub-chapters (max 3 levels deep) - Every linked file must exist; mdBook creates empty files for missing entries - Use `-` prefix for all entries, not `*` - Prefix and suffix chapters (outside parts) appear on every page Rules for `book.toml`: - Always set `[book]` title, authors, description, language - Enable `[output.html.search]` for searchability - Set `[output.html]` git-repository-url for "edit this page" links - Configure `[build]` build-dir if CI/CD needs it ### Phase 3: Write Chapters For each chapter, follow this process: 1. **Choose the template** from `templates/` matching the chapter type. 2. **Write the first draft** following the writing style guide. 3. **Add code examples** — every code block must be: - Complete and compilable (or clearly marked as pseudocode) - Annotated with the language identifier (` ```rust `, ` ```toml `, etc.) - Using `# ` prefix for hidden lines in Rust examples (mdBook convention) - Tested if possible (link to actual test files or use `mdbook test`) 4. **Add cross-references** — use relative links `[text](../path/file.md#anchor)`. 5. **Add admonitions** where needed — use mdBook's built-in or preprocessor syntax. ### Phase 4: Review & Polish After writing, perform these checks: 1. **Build test**: Run `mdbook build` and fix all warnings. 2. **Link check**: Verify all internal and external links work. 3. **Code test**: Run `mdbook test` to verify Rust code examples compile. 4. **Consistency check**: Terminology, formatting, heading levels, voice. 5. **Reader test**: Can someone with zero context follow the getting-started guide end-to-end? 6. **Search test**: Do key terms appear in search results? ## Chapter Types & Templates | Type | Template | When to use | |------|----------|-------------| | Getting Started | `templates/getting-started.md` | Installation, first steps, quick wins | | Concept/Guide | `templates/guide.md` | Explaining how/why something works | | Tutorial | `templates/tutorial.md` | Step-by-step hands-on walkthrough | | API Reference | `templates/api-reference.md` | Per-module or per-type documentation | | Architecture | `templates/architecture.md` | System design, internals, decisions | | Operations | `templates/operations.md` | Deployment, config, monitoring, troubleshooting | | Changelog | `templates/changelog.md` | Version history following Keep a Changelog | ## Writing Principles (Quick Reference) Full details in `references/writing-style.md`. Key rules: 1. **Lead with the user's goal**, not the tool's feature. 2. **One idea per paragraph**. Short paragraphs (3-5 sentences max). 3. **Active voice, imperative mood** for instructions: "Run the command" not "The command should be run". 4. **Show, then explain**: code example first, explanation after. 5. **Progressive disclosure**: basic → intermediate → advanced within each chapter. 6. **No orphan headings**: every H2 must have content before the next H2. 7. **Consistent terminology**: define terms on first use, use the same term throughout. 8. **Meaningful link text**: "see the [configuration guide](config.md)" not "click [here](config.md)". ## mdBook-Specific Features to Use - **`{{#include}}`** — include code from actual source files to keep examples in sync - **`{{#rustdoc_include}}`** — include Rust code with line range from source - **Hidden lines** — prefix with `# ` in Rust blocks to hide boilerplate - **`{{#playground}}`** — embed Rust Playground links for interactive examples - **Preprocessors** — `mdbook-mermaid` for diagrams, `mdbook-toc` for auto TOC, `mdbook-admonish` for callouts - **Search** — enabled by default, ensure key terms are in headings and first paragraphs - **Print page** — all chapters merge into one; ensure each chapter works standalone ## Quality Checklist (Per Chapter) Before marking a chapter complete: - [ ] Title is descriptive and matches SUMMARY.md entry - [ ] Opens with 1-2 sentences explaining what the reader will learn - [ ] Prerequisites listed if any - [ ] All code examples are complete and tested - [ ] Hidden lines used for boilerplate in Rust examples - [ ] Cross-references to related chapters included - [ ] No broken internal links - [ ] Consistent heading hierarchy (H1 = chapter title, H2 = sections, H3 = subsections) - [ ] Admonitions used for warnings, tips, important notes - [ ] No walls of text — broken up with code, lists, or diagrams where helpful ## Iteration Strategy For large documentation projects: 1. **Skeleton first** — create all files with H1 + one-line description 2. **P0 chapters** — write getting-started and most-needed guides 3. **Dog-food** — have someone follow the docs; fix every point of confusion 4. **P1 chapters** — architecture, advanced guides, operations 5. **P2 chapters** — deep dives, edge cases, contributor docs 6. **Maintain** — update docs as part of every feature PR