Skip to content

Documentation Guide

User-facing documentation as an opt-in workflow deliverable.

The toolkit can manage end-user documentation alongside code. When enabled, documentation is scaffolded at bootstrap, tracked per feature in SPECchen, updated during build, validated during review, and built during deployment.

When to Use

Enable user documentation when the project:

  • Serves end users who need onboarding, feature guides, or help content
  • Exposes APIs that external consumers need to integrate with
  • Requires a developer platform or SDK documentation site
  • Needs branded release notes or changelogs for stakeholders

Skip if the project is an internal tool, library consumed only by your team, or a prototype that won't ship documentation.

Setup

Option A: During bootstrap

Run /1-bootstrap and accept the "User Documentation Site" prompt. This creates:

docs/user-manual/
├── mkdocs.yml              # MkDocs Material config
├── docs/
│   ├── index.md            # Welcome page
│   ├── getting-started.md  # End-user onboarding
│   └── features/           # One page per major feature
│       └── .gitkeep

Option B: Manual setup

Create docs/user-manual/ with a mkdocs.yml at any time. The workflow detects the directory automatically — no configuration flag needed.

Detection

Every phase checks: does docs/user-manual/mkdocs.yml exist? If yes, documentation steps activate. If no, the workflow behaves exactly as before.

Per-Feature Workflow

When docs/user-manual/ exists, each SPECchen includes a Documentation Requirements section:

### Documentation Requirements
- [ ] Feature documented in docs/user-manual/docs/features/[feature-name].md
- [ ] Getting started guide updated if user onboarding changes
- [ ] API endpoints documented (if user-facing API)
- [ ] Screenshots/diagrams updated to reflect UI changes

This checklist is generated automatically by /pd-5-specchen when the docs directory is detected.

During Build (Phase 3)

After implementing a feature, update the corresponding documentation page before running the full test suite:

  1. Create or update docs/user-manual/docs/features/[feature-name].md
  2. Update getting-started.md if the user onboarding flow changed
  3. Add screenshots or diagrams if the UI changed

The implementation orchestrator reminds you about documentation requirements when they exist in the SPECchen. This is advisory — it does not block the build.

During Review (Phase 4)

The review phase checks documentation completeness:

  1. Reads the SPECchen for documentation requirement checklist items
  2. Verifies that referenced documentation files exist and are non-empty
  3. Reports findings as Medium severity in the review report

The .review-gate.md file includes:

docs_status: COMPLETE    # or INCOMPLETE or N/A
docs_missing: []         # list of missing files

Documentation issues do not block the review gate but are flagged for attention.

During Deploy (Phase 5)

The deployment orchestrator builds the documentation site:

  1. Runs mkdocs build --strict in docs/user-manual/
  2. Build failures block deployment (broken links, missing pages)
  3. Build warnings are reported but do not block

This ensures no broken documentation ships with a release.

MkDocs Configuration

The scaffolded mkdocs.yml uses MkDocs Material with the same deep orange theme as the toolkit documentation. Customize as needed for your project:

  • Add nav sections for new feature categories
  • Configure search, syntax highlighting, and code copy
  • Add custom CSS for project-specific branding