Documentation Process¶

This guide describes how to update Swisper's living documentation after shipping a feature. It covers when documentation updates are needed, who is responsible, and how to use the Documentation Agent to draft content efficiently.

Audience: Engineers, tech leads, and anyone who ships features in Swisper.

Time commitment: 1-2 hours per feature (the agent drafts, you review).

When to Update Documentation¶

Documentation updates are triggered when a feature implementation is complete — the PR is merged or ready to merge. This is Phase 6 (Living Documentation) in the Swisper PDLC.

Trigger: Feature PR merged to main (or ready to merge).

Rule: Documentation is part of the Definition of Done. A feature is not "done" until its living documentation is updated and the site builds successfully.

What Triggers a Documentation Update¶

What Does NOT Trigger a Documentation Update¶

• Bug fixes (unless the fix changes documented behavior)
• Dependency updates (unless they change architecture or operations)
• Refactoring with no behavior change (unless it changes the module structure)
• Typo or formatting fixes in code

What to Update¶

Each module has up to three audience sections. Update the sections affected by your change.

Module Structure¶

Every documented module lives at docs/products/<product>/modules/<module-name>/ with this structure:

docs/products/<product>/modules/<module-name>/
├── index.md          # Module landing page (links to sections)
├── overview.md       # What it does, who it serves (business audience)
├── architecture.md   # How it's designed (architects, senior engineers)
└── operations.md     # How to run and monitor it (ops, SRE) — if applicable

Which Sections to Update¶

When in doubt: Update the Architecture section. It is the most commonly affected section for engineering changes.

Who Is Responsible¶

The engineer who reviews and approves the agent's output owns the content. The last_updated_by field must always be a real person's name — never "Documentation Agent", "AI Assistant", "Cursor", or "Claude".

How to Invoke the Documentation Agent¶

Prerequisites¶

Before starting, ensure you have:

• [ ] The Feature Vision document (finalized)
• [ ] The Solution Architecture Spec (finalized or at least drafted)
• [ ] The codebase for the module available locally
• [ ] Access to the Swisper_Documentation repository

Step-by-Step: Ongoing Documentation (After a Feature Ships)¶

1. Open Cursor in the Swisper_Documentation repo.

2. Start a new chat session and paste this prompt:

You are the Documentation Agent. Your job is to create/update
living documentation for a module.

Open and read this working template — it contains your full
operating instructions:
templates/documents/living-doc.md

Inputs:
- Feature Vision: work/products/<PRODUCT>/epics/EPC_<NNN>_<slug>/features/FEAT_<NNN>_<slug>/vision_FEAT_<NNN>_<slug>_v1.md
- Solution Architecture Spec: work/products/<PRODUCT>/epics/EPC_<NNN>_<slug>/features/FEAT_<NNN>_<slug>/spec_FEAT_<NNN>_<slug>_v1.md
- Codebase: <path to module source code in helvetiq repo>
- Module name: <display name, e.g., "Voice System">
- Module slug: <folder name, e.g., "voice-system">

Replace the placeholder paths with actual paths to your Feature Vision, Spec, and codebase module.

3. The agent reads your inputs and drafts each section sequentially:

• overview.md — from the Feature Vision (business-facing)
• architecture.md — from the Spec + codebase (design, diagrams)
• operations.md — from Spec NFRs + codebase (if applicable)

The agent will ask you to confirm after each section before moving on.

4. Review each section as the agent drafts it.

Correct inaccuracies, add context the agent could not extract from the inputs. The agent works from documents and code — you bring the context that only the person who built the feature has.

5. The agent performs a gap review.

The agent flags any areas where the input was insufficient to draft content. You can provide the missing information or accept the gap (it will be marked for future follow-up).

6. The agent finalizes frontmatter.

The agent sets last_updated_by to your name, updates version and last_updated date. Verify this is correct before committing.

7. Commit the files and open a PR.

git add docs/modules/<module-name>/
git commit -m "docs: update <module-name> living documentation"
git push

CI/CD builds the Zensical site, validates links, and deploys.

Step-by-Step: Legacy Migration¶

For migrating existing documents from Documentation/ into the module structure (one-time activity during initial population):

You are the Documentation Agent. Your job is to migrate a legacy
document into the living documentation structure.

Open and read this working template:
templates/documents/living-doc.md

Mode: migration
Legacy doc: Documentation/<LEGACY_DOC_NAME>.md
Target: docs/products/<product>/modules/<module-name>/
Codebase: <path to module source code in helvetiq repo>
Module name: <display name>
Module slug: <folder name>

The workflow is the same as ongoing documentation, but the agent reads from the legacy document instead of a Feature Vision and Spec. The agent adds a migration disclaimer to the frontmatter.

Template References¶

The Documentation Agent uses these templates to produce consistent output:

Working Template (Agent Instructions)¶

Audience Templates (Output Structure)¶

Each audience template defines the required sections, quality criteria, examples of good and bad output, and a completion checklist. The agent follows these templates to produce structured, consistent documentation.

Where Output Goes¶

All module documentation is written to docs/products/<product>/modules/<module-slug>/:

docs/
├── products/
│   └── swisper/
│       ├── modules/
│       │   ├── voice-system/
│       │   │   ├── index.md
│       │   │   ├── overview.md
│       │   │   ├── architecture.md
│       │   │   └── operations.md
│       │   ├── hitl-system/
│       │   │   ├── index.md
│       │   │   ├── overview.md
│       │   │   └── architecture.md
│       │   └── ...
│       └── guides/          ← product-specific guides
└── guides/
    └── documentation-process.md   ← this guide (cross-cutting)

Product-specific guides go to docs/products/<product>/guides/. Cross-cutting guides go to docs/guides/.

Review Process¶

What to Review¶

When reviewing the Documentation Agent's output, check:

1. Accuracy: Does the content match what was actually built? The agent works from specs and code, but specs describe intended design while code shows actual implementation. Where they differ, documentation must reflect what the code actually does.

2. Completeness: Are all relevant aspects of the feature covered? Did the agent miss anything that only the person who built it would know?

3. Audience appropriateness: Is the Overview written in plain language (no jargon)? Is the Architecture section written for architects (not business stakeholders)? Is Operations actionable (specific commands, thresholds, not vague guidance)?

4. Gaps flagged properly: Did the agent flag gaps where it lacked information, rather than inventing content?

Approval¶

Documentation PRs can be self-approved by the engineer who reviewed the agent's output. No additional human review is required (the agent review + your review is sufficient).

If you are unsure about the accuracy of a section, request a review from the tech lead or the architect who designed the feature.

Verification Checklist¶

Before merging your documentation PR, verify all of the following:

Build Verification¶

# Both steps must pass — this is the quality gate
zensical build --clean    # Site builds with zero warnings
lychee site/              # Link validation — zero broken links

If either step fails, fix the issue before merging. Common problems:

Content Checklist¶

• [ ] No placeholder content — no [TODO], [placeholder], [to be documented], or template example text left in
• [ ] No empty sections — every heading has substantive content below it
• [ ] Frontmatter complete — all required fields present per documentation standards
• [ ] Author is a real person — last_updated_by is your name, not an agent name
• [ ] Source of truth linked — source_of_truth references the Feature Vision and/or Spec
• [ ] Changelog entry added — specific and action-oriented (not "Updated documentation")
• [ ] Mermaid diagrams valid — Architecture sections should have at least one diagram
• [ ] Internal links resolve — cross-references point to real files with correct relative paths
• [ ] Module index updated — docs/modules/<name>/index.md links to all created sections

Frontmatter Example¶

---
title: "Voice System — Overview"
doc_type: "living"
status: "draft"
product_id: "PRODUCT_swisper"
version: "v1.0"
created: "2026-02-16"
last_updated: "2026-02-16"
last_updated_by: "Heiko Sundermann"
source_of_truth: "work/epics/EPC_003_voice/features/FEAT_005_streaming_tts/spec_FEAT_005_streaming_tts_v1.md"
changelog:
  - version: "v1.0"
    date: "2026-02-16"
    changes: "Initial content. Added streaming TTS architecture and configuration. Source: spec_FEAT_005_v1.md."
---

Quick Reference¶

WHEN:    Feature PR merged (or ready to merge)
WHO:     Engineer who shipped it + Documentation Agent
WHERE:   docs/modules/<module-slug>/
HOW:     Invoke agent with Working Template + Feature Vision + Spec + codebase
REVIEW:  Engineer reviews agent output, corrects, approves
VERIFY:  zensical build --clean && lychee site/
COMMIT:  PR to feature branch (or main)
DONE:    Site deploys, docs are live