9.4 KiB
Documentation System
Version: {{VERSION}} Last Updated: {{DATE}} Status: {{STATUS}}
Overview
This documentation system provides comprehensive technical and operational documentation following industry standards (ISO/IEC/IEEE 29148, arc42, C4 Model, Michael Nygard's ADR format).
Documentation is organized into three main areas:
- Project Documentation - Requirements, architecture, technical specifications
- Reference Documentation - Architecture decisions (ADRs), reusable patterns (Guides), API references (Manuals)
- Task Management - Linear workflow, task tracking rules, kanban board
General Documentation Standards
All documentation in this system follows these conventions:
SCOPE Tags
Every document contains HTML comment tags defining its boundaries:
<!-- SCOPE: What this document CONTAINS -->
<!-- DO NOT add here: What belongs elsewhere → where to find it -->
Purpose: Prevent content duplication, maintain single source of truth, redirect to correct location.
Example:
<!-- SCOPE: Project requirements ONLY. Functional requirements ONLY. -->
<!-- DO NOT add here: Architecture details → architecture.md, Implementation → Task descriptions -->
Maintenance Sections
All documents contain a Maintenance section with:
| Field | Description | Example |
|---|---|---|
| Update Triggers | When to update the document | "When changing acceptance criteria (Non-Functional Requirements are forbidden here)" |
| Verification | How to verify document is current | "Check all FR-XXX IDs referenced in tests exist" |
| Last Updated | Date of last modification | "2025-11-15" |
Sequential Numbering
Rule: Phases/Sections/Steps use sequential integers: 1, 2, 3, 4 (NOT 1, 1.5, 2).
Exceptions:
| Case | Format | Example | When Valid |
|---|---|---|---|
| Conditional Branching | Letter suffixes | Phase 4a (CREATE), Phase 4b (REPLAN), Phase 5 | Mutually exclusive paths (EITHER A OR B) |
| Loop Internals | Steps inside Phase | Phase 3: Loop → Step 1 → Step 2 → Repeat | Cyclic workflows with repeated sub-steps |
Important: When inserting new items, renumber all subsequent items.
Placeholder Conventions
Documents use placeholders for registry updates:
| Placeholder | Location | Purpose | Updated By |
|---|---|---|---|
{{ADR_LIST}} |
reference/README.md | ADR registry | ln-322-adr-creator |
{{GUIDE_LIST}} |
reference/README.md | Guide registry | ln-321-guide-creator |
{{MANUAL_LIST}} |
reference/README.md | Manual registry | ln-323-manual-creator |
Usage: Skills automatically add new entries BEFORE the placeholder using Edit tool.
Writing Guidelines (Progressive Disclosure Pattern)
All documentation follows token-efficient formatting rules:
| Content Type | Format | Rationale |
|---|---|---|
| Skill descriptions | < 200 chars in SKILL.md frontmatter | Clarity, focused scope |
| Workflows | Reference table with link to SKILL.md | Avoid duplication (DRY) |
| Examples | Table rows (verdict + rationale) | 60-80% more compact than paragraphs |
| Lists | Bullet points with inline details | Progressive disclosure |
| References | One-line format (source - topics - insight) | Scannable, no verbose paragraphs |
| Comparisons | Table with columns | Visual clarity, easy scanning |
| Step-by-step processes | Inline arrow notation (Step 1 → Step 2 → Step 3) | Compact flow representation |
Verbose content is justified for:
- ❌ Anti-patterns (educational value - prevents mistakes)
- 🎓 Complex architectural explanations (orchestrator patterns, state machines)
- ⚠️ Critical rules with rationale (INVEST criteria, task sizing)
Compression targets:
- Main documentation files: < 500 lines (optimal: 300-400 lines)
- README hubs: < 200 lines
- Individual guides: < 800 lines (optimal: 400-600 lines)
Documentation Standards
Full documentation requirements: See documentation_standards.md
Key highlights:
- Claude Code Integration - CLAUDE.md ≤100 lines, @-sourcing, sessionStart hooks
- AI-Friendly Writing - Second person, active voice, max 25 words/sentence
- Code Examples - All examples runnable, realistic names, show expected output
- DIATAXIS Framework - Organize docs into Tutorial/How-to/Reference/Explanation
- Security - Never commit secrets, use .env.example templates
- Conventional Commits - Structured commit messages for auto-changelog
Total: 60 requirements in 12 categories. See documentation_standards.md for complete details.
Documentation Structure
1. Project Documentation
Core project documentation created by ln-114-project-docs-creator skill:
- README.md - Project documentation hub
- requirements.md - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization
- architecture.md - System architecture (C4 Model, arc42)
- technical_specification.md - Implementation details
Purpose: Define WHAT we build and WHY.
Created by: ln-114-project-docs-creator
2. Reference Documentation
Reusable knowledge base and architecture decisions:
- ADRs - Architecture Decision Records (format:
adr-NNN-slug.md) - Guides - Project patterns and best practices (format:
NN-pattern-name.md) - Manuals - Package API references (format:
package-version.md)
Purpose: Document HOW we build (patterns, decisions, APIs).
Created by: ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator
3. Task Management System
Linear integration and workflow rules:
- README.md - Task lifecycle, Linear integration rules, workflow skills
- kanban_board.md - Live navigation to active tasks
Purpose: Define HOW we track and manage work.
Created by: ln-111-docs-creator (Phase 2, Phase 9-10)
Standards Compliance
This documentation system follows:
| Standard | Application | Reference |
|---|---|---|
| ISO/IEC/IEEE 29148:2018 | Requirements Engineering | requirements.md |
| ISO/IEC/IEEE 42010:2022 | Architecture Description | architecture.md |
| arc42 Template | Software architecture documentation | architecture.md |
| C4 Model | Software architecture visualization | architecture.md |
| Michael Nygard's ADR Format | Architecture Decision Records | reference/adrs/ |
| MoSCoW Prioritization | Requirements prioritization | requirements.md |
Contributing to Documentation
When updating documentation:
- Check SCOPE tags at top of document to ensure changes belong there
- Update Maintenance > Last Updated date in the modified document
- Update registry if adding new documents:
- ADRs, Guides, Manuals → automatically updated by skills
- Project docs → update project/README.md manually
- Follow sequential numbering rules (no decimals unless conditional branching)
- Add placeholders if creating new document types
- Verify links after structural changes
Quick Navigation
| Area | Key Documents | Skills |
|---|---|---|
| Standards | documentation_standards.md | ln-111-root-docs-creator, ln-121-structure-validator |
| Project | requirements.md, architecture.md, technical_specification.md | ln-114-project-docs-creator, ln-122-content-updater |
| Reference | ADRs, Guides, Manuals | ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator |
| Tasks | kanban_board.md, README.md | ln-210-epic-coordinator, ln-220-story-coordinator, ln-310-story-decomposer |
Maintenance
Update Triggers:
- When adding new documentation areas (new subdirectories)
- When changing general documentation standards (SCOPE, Maintenance, Sequential Numbering)
- When changing writing guidelines or documentation formatting standards
- When adding new placeholder conventions
- When updating compliance standards
Verification:
- All links to subdirectory READMEs are valid
- SCOPE tags accurately reflect document boundaries
- Placeholder conventions documented for all registries
- Standards Compliance table references correct documents
Last Updated: {{DATE}}
Template Version: 1.1.0 Template Last Updated: 2025-11-16