Doc Export

Documentation Export

Create self-contained documentation packages from codebases.

Goal

Produce a minimal, accurate, well-organized documentation set that fully describes a system without requiring source code access.

Process

1. Audit Existing Documentation

Inventory current docs:

find ./docs -name "*.md" -type f
ls -la ./docs/

For each file, assess:

• Purpose: What does it document?
• Currency: Does it reflect current implementation?
• Overlap: Does it duplicate other docs?
• Completeness: What's missing?

2. Explore the Codebase

Understand what needs documenting:

• Domain model: Core types, entities, relationships
• Architecture: Packages, layers, key design decisions
• Commands/API: User-facing interfaces
• Data model: Database schema, storage

Use grep/glob to find domain types, command definitions, schema files.

3. Plan Document Structure

Target 3-5 focused documents:

Adjust based on project type (CLI, library, service, etc.).

4. Consolidate and Rename

Apply consistent naming:

• Use SCREAMING-KEBAB-CASE.md (e.g., CLI-REFERENCE.md)
• Delete sparse/outdated files
• Merge related content into focused documents
• Remove duplicate information

5. Update Content

For each document:

Spec/Reference docs:

• Verify all commands/endpoints documented
• Update field lists to match current schema
• Fix incorrect states, types, enums
• Add missing features (check recent commits)
• Remove deprecated/unimplemented features

Architecture docs:

• Document actual package structure
• Explain key design decisions
• Cover data model and storage
• Note what's implemented vs planned

Domain model:

• Define all core concepts
• Show relationships between entities
• Clarify terminology
• Note implementation status

6. Verify Cross-References

Check for broken references:

grep -r "docs/[A-Z]" ./docs/
grep -rn "\.md" ./docs/ | grep -v "^Binary"

Update all internal links to match renamed files.

7. Final Review

Checklist:

• Each document has a clear, single purpose
• No duplicate information across documents
• All cross-references valid
• Naming convention consistent
• Outdated content removed
• Missing features documented
• Implementation status noted where relevant
• Documents are self-contained (no broken image refs, etc.)

Document Guidelines

SPEC.md

• Comprehensive product specification
• Include: goals, data model, command/API reference, behaviors
• This is the authoritative reference
• 30-50KB typical

DOMAIN-MODEL.md

• Conceptual, not implementation-focused
• Define business terms and relationships
• Include diagrams (Mermaid) if helpful
• Note what's implemented vs aspirational
• 10-15KB typical

CLI-REFERENCE.md / API-REFERENCE.md

• Feature-oriented, not exhaustive
• Include common workflows and examples
• Group by task, not alphabetically
• 15-20KB typical

ARCHITECTURE.md

• Technical decisions and rationale
• Package/module structure
• Key patterns and conventions
• Design decisions explained
• 10-15KB typical

Anti-patterns

• Creating README.md or CHANGELOG.md (not useful for external consumption)
• Keeping sparse files (< 20 lines of content)
• Duplicating content across documents
• Referencing non-existent files or images
• Including implementation details in conceptual docs
• Documenting aspirational features as implemented