Skip to main content

Feature: Documentation Site

Version: 1.0.0 Last Reviewed: 2026-02-13 Status: Approved

User Story​

As a developer or caregiver, I can find accurate, up-to-date documentation at a single URL so I can set up, use, or contribute to Baby Basics without asking for help.

Overview​

Baby Basics publishes a Docusaurus documentation site serving two audiences: users (parents, family, caregivers) and developers (self-hosters, contributors, API consumers). Content is organized by progressive disclosure — users find what they need in seconds, developers can drill into architecture and specs.

Audiences​

AudienceNeedsSections
UsersHow to use the app, troubleshootingQuick Start, Feature Guides
DevelopersHow to build, deploy, extendSetup Guide, Self-Hosting, API Reference, Architecture, Specs

Site Structure​

apps/docs/docs/
├── index.md                    # Welcome + audience routing
├── getting-started/
│   ├── quick-start.md          # Users: 30-second setup
│   ├── setup-guide.md          # Devs: local development environment
│   └── self-hosting.md         # Devs: deploy your own instance
├── guides/                     # Per-feature user guides (added as features ship)
│   ├── _template.md            # Template for new guides (not published)
│   └── troubleshooting.md      # Common issues + fixes
├── api/
│   └── index.md                # API conventions + generated endpoint docs
├── architecture/
│   └── overview.md             # System architecture, tech stack, design decisions
└── specs/
    ├── index.md                # What specs are + how to read them
    └── *.md                    # Auto-synced from docs/specs/ at build time

Content Types​

1. Feature Guide (user-facing)​

Written when a feature ships. Describes what the feature does and how to use it.

Template:

---
sidebar_position: N
---

# Feature Name

One-sentence description of what this feature does.

## How It Works

Step-by-step usage instructions. Use numbered steps for multi-step flows,
bullet points for options.

<!-- SCREENSHOT: Description of what to capture -->

## Tips

- Helpful tip 1
- Helpful tip 2

## Related

- [Other Guide](link)

Rules:

  • Only describe shipped, working functionality
  • Never describe planned or aspirational features as if they exist
  • Use present tense ("Tap the button" not "You will be able to tap")
  • Include <!-- SCREENSHOT: description --> placeholders where visuals would help
  • Keep it short — parents are sleep-deprived

2. Developer Page (developer-facing)​

Describes technical details: setup, architecture, deployment.

Rules:

  • Every command must be tested and working
  • Include the exact file paths and commands
  • Keep in sync with actual codebase — if a file moves, update the docs

3. API Reference (auto-generated)​

Generated from the OpenAPI spec exported by the running Fastify API.

Pipeline: /docs-sync skill exports the spec → docusaurus-plugin-openapi-docs renders it.

Rules:

  • Never hand-write API endpoint docs — they come from the OpenAPI spec
  • The api/index.md overview page IS hand-written (auth, response format conventions)

4. Specs (synced from source)​

Copied from docs/specs/ at build time via scripts/sync-specs.sh. These are the source of truth for feature requirements.

Rules:

  • Never edit specs in apps/docs/docs/specs/ — edit the source at docs/specs/
  • Synced copies are gitignored

When to Document​

Feature Agent Responsibilities (first pass)​

When a feature agent completes a feature, they:

  1. Write a feature guide in apps/docs/docs/guides/<feature>.md using the template
  2. Update apps/docs/docs/architecture/overview.md if the feature introduces new architecture
  3. Update apps/docs/docs/getting-started/setup-guide.md if setup steps changed
  4. Add screenshot placeholders where visuals would help
  5. Log any observations: hearth log --tag docs "[BB-<id>]: <observation>"

Dedicated Docs Pass (polish pass)​

Periodically (after a batch of features ships), a dedicated docs pass:

  1. Processes all --tag docs log entries
  2. Reviews and polishes feature guides for tone, accuracy, completeness
  3. Updates cross-references between guides
  4. Captures screenshots (replaces <!-- SCREENSHOT: --> placeholders)
  5. Verifies all setup/deploy instructions still work
  6. Runs the docs-auditor agent for a comprehensive accuracy check

Adding a New Feature's Docs (generic checklist)​

When feature X ships:

  • apps/docs/docs/guides/<feature>.md created from template
  • Guide describes only shipped functionality (no aspirational content)
  • Screenshot placeholders added where helpful
  • architecture/overview.md updated if new components/patterns introduced
  • getting-started/setup-guide.md updated if setup steps changed
  • troubleshooting.md updated with known issues for this feature
  • API reference auto-generates correctly (/docs-sync)

Quality Criteria​

Accuracy (hard requirement)​

  • Every command in the docs must work when copy-pasted
  • Every described feature must actually exist and work as described
  • File paths must match the actual codebase
  • No aspirational content presented as current reality

Completeness​

  • Every shipped feature has a guide
  • Developer setup guide covers the full local development flow
  • Self-hosting guide covers the full deployment flow
  • Troubleshooting covers known issues

Freshness​

  • Docs checked after every batch of features (via /docs-check skill)
  • Full audit every 2 weeks or after major changes (via docs-auditor agent)
  • Audit timestamps tracked via hearth log --tag docs-audit

Screenshot Convention​

Use HTML comments as placeholders:

<!-- SCREENSHOT: Description of what the screenshot should show -->

Screenshots are captured during dedicated docs passes, not during feature development. Feature agents add placeholders; the docs pass fills them.

Audit Process​

Lightweight Check (/docs-check skill)​

Run frequently — after any feature, before PRs, anytime.

  • Verifies spec sync status
  • Counts screenshot placeholders
  • Reports unprocessed --tag docs entries
  • Reports time since last full audit

Deep Audit (docs-auditor agent)​

Run every 2 weeks or after a batch of features ships.

  • Verifies every factual claim against the codebase
  • Tests setup/deploy instructions
  • Reports missing docs for shipped features
  • Checks for stale/outdated content
  • Logs audit completion: hearth log --tag docs-audit "Audit complete: N issues found"

MVP Scope​

  • Docusaurus site with docs-only mode
  • Auto-synced specs from docs/specs/
  • Developer pages: setup guide, self-hosting, architecture overview
  • API reference placeholder (real spec when API is running)
  • Feature guide template (guides added as features ship)
  • /docs-sync and /docs-check skills
  • docs-auditor agent for periodic deep audits

NOT in MVP​

  • Custom Docusaurus theme/branding (Post-MVP)
  • Search (Algolia DocSearch — Post-MVP)
  • Versioned docs (Post-MVP)
  • Blog section (Post-MVP)
  • Automated screenshot capture CI (Post-MVP)
  • Translations/i18n (Post-MVP)

Acceptance Criteria​

  • Docs site builds successfully (npm run build in apps/docs/)
  • All specs auto-sync from docs/specs/ to docs site
  • Developer setup guide matches actual codebase (commands work)
  • Self-hosting guide matches actual infra scripts
  • Architecture overview reflects current tech stack accurately
  • No feature guides exist for unbuilt features
  • Feature guide template exists for agents to follow
  • /docs-check skill reports time since last audit
  • docs-auditor agent can run a full accuracy audit
  • Sage wisdom rule reminds about periodic audits

Test Cases​

  1. Build passes: cd apps/docs && npm run build succeeds with zero errors
  2. Spec sync: Add a new spec to docs/specs/, run sync, verify it appears in docs site
  3. Setup guide accuracy: Follow the setup guide on a clean checkout, verify it works
  4. Audit detects staleness: Introduce an intentional inaccuracy, run auditor, verify it's caught
  5. No aspirational content: Grep for features that don't exist yet, verify no guides describe them as working

Boundaries​

  • This spec covers the documentation site only, not the feature specs themselves
  • Feature specs are governed by their own versioning (see CLAUDE.md)
  • The docs site is a consumer of specs, not a producer
  • iOS screenshot capture tooling is a separate concern (Post-MVP)