6.9 KiB
6.9 KiB
Modular Documentation Standards
The 500-line rule and document organization.
Related: DOCUMENTATION_UPDATES.md | INDEX_MAP.md
Overview
This document establishes standards for modular documentation, including the 500-line maximum rule. Modular docs are easier to maintain, navigate, and consume (especially for AI agents trying to save tokens).
The 500-Line Rule
Why 500 Lines?
RATIONALE:
1. Readability - Long docs are hard to navigate
2. Maintainability - Smaller files easier to update
3. Token efficiency - AI agents load less context
4. Focus - Each doc should have one clear purpose
5. Searchability - Easier to find specific content
How to Count Lines
WHAT COUNTS:
- All lines in the file
- Blank lines
- Code blocks
- Tables
WHAT DOESN'T COUNT:
- (Everything counts)
CHECK LINE COUNT:
wc -l <file.md>
Enforcement
# Check all docs under 500 lines
find docs -name "*.md" -exec sh -c 'lines=$(wc -l < "$1"); if [ "$lines" -gt 500 ]; then echo "OVER LIMIT: $1 ($lines lines)"; fi' _ {} \;
# Automated check in CI
- name: Check doc length
run: |
for file in $(find docs -name "*.md"); do
lines=$(wc -l < "$file")
if [ "$lines" -gt 500 ]; then
echo "ERROR: $file has $lines lines (max 500)"
exit 1
fi
done
Document Structure Standards
Required Sections
Every document MUST have:
# Title
> One-line description
**Related:** [links to related docs]
---
## Overview
Brief introduction
---
[Content sections...]
---
## Quick Reference
Summary box or table
---
**Last Updated:** YYYY-MM-DD
**Line Count:** ~XXX
Optional Sections
- Prerequisites
- Examples
- Troubleshooting
- FAQ
- Related Documents (extended)
Section Order
1. Title and metadata
2. Overview
3. Main content (logical order)
4. Quick Reference
5. Footer (updated date, line count)
Breaking Up Large Documents
When to Split
SPLIT WHEN:
- Document exceeds 400 lines (approaching limit)
- Document covers multiple distinct topics
- Sections could standalone
- Different audiences for different sections
How to Split
SPLITTING STRATEGY:
1. Identify natural boundaries
- Each major section could be its own doc
2. Create parent INDEX.md
- Links to all child documents
- Brief summary of each
3. Move sections to new files
- One topic per file
- Under 500 lines each
4. Update cross-references
- Fix all internal links
- Update INDEX_MAP.md and HEADER_MAP.md
Split Example
BEFORE (one large doc):
COMPREHENSIVE_GUIDE.md (800 lines)
AFTER (multiple focused docs):
guide/
├── INDEX.md (50 lines)
├── GETTING_STARTED.md (200 lines)
├── CONFIGURATION.md (250 lines)
├── ADVANCED_USAGE.md (200 lines)
└── TROUBLESHOOTING.md (150 lines)
Cross-Reference Patterns
# In split documents, reference siblings:
See [Configuration](./CONFIGURATION.md) for setup options.
For common issues, check [Troubleshooting](./TROUBLESHOOTING.md).
Return to [Guide Index](./INDEX.md).
Directory Organization
Standard Directory Structure
docs/
├── INDEX.md # Root navigation
├── AGENT_GUARDRAILS.md # Core safety doc
├── workflows/ # How-to procedures
│ ├── INDEX.md
│ └── [workflow docs]
├── standards/ # Documentation standards
│ ├── INDEX.md
│ └── [standards docs]
├── sprints/ # Task framework
│ ├── INDEX.md
│ ├── SPRINT_TEMPLATE.md
│ └── archive/
└── [topic]/ # Additional topics
├── INDEX.md
└── [topic docs]
Naming Conventions
FILE NAMING:
- UPPERCASE for top-level docs (README.md, CHANGELOG.md)
- SCREAMING_CASE for guides (GETTING_STARTED.md)
- kebab-case for technical docs if preferred
- Always .md extension
DIRECTORY NAMING:
- lowercase
- descriptive
- no spaces (use hyphens)
INDEX.md Pattern
Every directory with multiple docs should have INDEX.md:
# [Directory Name] Index
> Navigation for [topic] documentation.
---
## Documents
| Document | Purpose |
|----------|---------|
| [DOC1.md](./DOC1.md) | Description |
| [DOC2.md](./DOC2.md) | Description |
---
## Quick Links
- Most used: [DOC1.md](./DOC1.md)
- Start here: [DOC2.md](./DOC2.md)
Module Dependencies
Explicit Dependencies
# At top of document, declare dependencies:
**Prerequisites:**
- Read [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md) first
- Familiarity with git basics
**Related:**
- [COMMIT_WORKFLOW.md](./COMMIT_WORKFLOW.md)
- [TESTING_VALIDATION.md](./TESTING_VALIDATION.md)
Circular Reference Prevention
AVOID:
DOC_A.md → "see DOC_B.md for details"
DOC_B.md → "see DOC_A.md for details"
INSTEAD:
DOC_A.md → "see DOC_B.md for X"
DOC_B.md → self-contained for its topic
Or create DOC_C.md for shared content.
Compliance Checklist
Before publishing any document:
[ ] Under 500 lines
[ ] Has required sections (Overview, Quick Reference)
[ ] Title describes content accurately
[ ] Related docs linked
[ ] Added to INDEX_MAP.md
[ ] Headers added to HEADER_MAP.md
[ ] Added to directory INDEX.md
[ ] No broken links
[ ] Markdown renders correctly
[ ] Last Updated date set
Quick Reference
+------------------------------------------------------------------+
| MODULAR DOCUMENTATION QUICK REFERENCE |
+------------------------------------------------------------------+
| THE 500-LINE RULE: |
| - Maximum 500 lines per document |
| - Check: wc -l <file.md> |
| - If over: split into multiple docs |
+------------------------------------------------------------------+
| REQUIRED SECTIONS: |
| # Title |
| ## Overview |
| [Content] |
| ## Quick Reference |
| Footer (date, line count) |
+------------------------------------------------------------------+
| NAMING: |
| - Files: SCREAMING_CASE.md |
| - Directories: lowercase |
| - Always include INDEX.md in directories |
+------------------------------------------------------------------+
Authored by: TheArchitectit Document Owner: Project Maintainers Last Updated: 2026-01-14 Line Count: ~280