Organizing Documentation

Organizing Documentation

Overview

Transform documentation from content-type organization (architecture/, testing/, api/) to intent-based organization (BUILD/, FIX/, UNDERSTAND/, LOOKUP/).

Announce at start: "I'm using the organizing-documentation skill to structure these docs by developer intent."

When to Use

• Setting up documentation for a new project
• Existing docs are hard to navigate
• New team members can't find what they need
• Same questions keep getting asked
• Docs exist but nobody reads them

The Process

Step 1: Audit Existing Documentation

List all docs and categorize by actual developer intent:

| File | Current Location | Developer Intent | New Location |
|------|-----------------|------------------|--------------|
| architecture.md | docs/ | Understand system | UNDERSTAND/core-systems/ |
| testing-guide.md | docs/ | Build tests | BUILD/03-TEST/ |
| error-codes.md | docs/ | Quick lookup | LOOKUP/ |
| debugging-tips.md | docs/ | Fix problems | FIX/investigation/ |

Key question: "When would a developer reach for this doc?"

Step 2: Create Directory Structure

mkdir -p docs/{BUILD/{00-START,01-DESIGN,02-IMPLEMENT,03-TEST,04-VERIFY},FIX/{symptoms,investigation,solutions},UNDERSTAND/{core-systems,evolution},LOOKUP}

Step 3: Populate 00-START First

Critical: This is the entry point. Include:

1. Prime directive - Non-negotiable project rules
2. Architecture overview - High-level system map
3. Coordinate systems/conventions - Domain-specific foundations

Without 00-START, developers skip prerequisites.

Step 4: Organize FIX by Symptoms

Wrong: Organize by root cause (memory-leaks/, type-errors/) Right: Organize by what developer sees (visual-bugs/, test-failures/)

FIX/symptoms/
├── visual-bugs/
│   ├── rendering-wrong.md
│   └── layout-broken.md
├── test-failures/
│   └── passes-locally-fails-ci.md
└── performance/
    └── slow-startup.md

Step 5: Create LOOKUP Quick References

Rule: < 30 seconds to find and use.

Good LOOKUP content:

• Keyboard shortcuts
• Command cheat sheets
• Error code tables
• ID registries
• One-page summaries

Bad LOOKUP content (move elsewhere):

• Tutorials (→ BUILD/02-IMPLEMENT)
• Explanations (→ UNDERSTAND)
• Debugging guides (→ FIX)

Step 6: Build INDEX.md

Create master index with purpose annotations:

## BUILD

| File | Title | Purpose |
|------|-------|---------|
| `00-START/prime-directive.md` | Prime Directive | Non-negotiable rules |
| `02-IMPLEMENT/patterns.md` | Code Patterns | How to implement features |

Purpose column is mandatory - it's the key to discoverability.

Step 7: Add Redirects

Don't break existing links. Create README.md in old locations:

# This content has moved

Documentation has been reorganized by developer intent.

- Architecture docs → `UNDERSTAND/core-systems/`
- Testing docs → `BUILD/03-TEST/`
- Quick references → `LOOKUP/`

See `docs/INDEX.md` for complete navigation.

Checklist

• All docs audited and categorized by intent
• BUILD/00-START has prerequisites
• FIX organized by symptoms, not causes
• LOOKUP items are < 30 second lookups
• INDEX.md has purpose column
• Old locations have redirects
• Internal links verified

Anti-Patterns

Don't:

• Create deep nesting (max 3 levels)
• Duplicate content across directories
• Put tutorials in LOOKUP
• Organize FIX by root cause
• Skip the INDEX.md

Do:

• Keep structure flat where possible
• Cross-reference between sections
• Update INDEX.md as docs change
• Test navigation with new team member

Additional Patterns

README-Per-Directory

Every directory needs README.md with consistent structure:

• Purpose statement
• "Use this when" section
• Navigation to contents
• Quick links to related sections

Use template: ${CLAUDE_PLUGIN_ROOT}templates/documentation-readme-template.md

Dual Navigation

Maintain parallel navigation:

• NAVIGATION.md - Task-based primary (80%)
• INDEX.md - Concept-based fallback (20%)

Naming Conventions

• ALLCAPS for document types: SUMMARY.md, QUICK-REFERENCE.md
• Numeric prefixes for sequence: 00-START/, 01-DESIGN/
• Lowercase-dashes for content: api-patterns.md

Progressive Disclosure

Provide multiple entry points by time budget:

• 5 min: TL;DR section
• 20 min: README + key sections
• 2 hours: Full documentation

Role-Based Paths

Create reading paths for different roles with:

• Goal statement
• Reading order
• Time estimate
• Key takeaway

Integration with Instruction Files

AGENTS.md and CLAUDE.md should reference the docs/ structure using progressive disclosure:

Pattern:

1. Keep 2-3 sentence summary in instruction file
2. Link to detailed doc: "See docs/BUILD/00-START/ for prerequisites"
3. AI fetches detailed docs only when needed

When reorganizing docs/:

• Update AGENTS.md/CLAUDE.md references to match new paths
• Use cipherpowers:maintaining-instruction-files to verify instruction file quality
• Verify links work after restructuring

Symlink strategy for multi-agent compatibility:

# Create symbolic link for multi-agent support
ln -s AGENTS.md CLAUDE.md

# Verify symlink works
ls -l CLAUDE.md  # Should show: CLAUDE.md -> AGENTS.md

Related Skills

Documentation workflow:

• Maintain docs: ${CLAUDE_PLUGIN_ROOT}skills/maintaining-docs-after-changes/SKILL.md
• Instruction files: ${CLAUDE_PLUGIN_ROOT}skills/maintaining-instruction-files/SKILL.md
• Capture learning: ${CLAUDE_PLUGIN_ROOT}skills/capturing-learning/SKILL.md

Specialized documentation:

• Research packages: ${CLAUDE_PLUGIN_ROOT}skills/creating-research-packages/SKILL.md
• Debugging docs: ${CLAUDE_PLUGIN_ROOT}skills/documenting-debugging-workflows/SKILL.md
• Quality gates: ${CLAUDE_PLUGIN_ROOT}skills/creating-quality-gates/SKILL.md

References

• Standards: ${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md
• README Template: ${CLAUDE_PLUGIN_ROOT}templates/documentation-readme-template.md
• Research Package Template: ${CLAUDE_PLUGIN_ROOT}templates/research-package-template.md
• Quick Reference Template: ${CLAUDE_PLUGIN_ROOT}templates/quick-reference-template.md
• Symptom Debugging Template: ${CLAUDE_PLUGIN_ROOT}templates/symptom-debugging-template.md
• Verification Checklist Template: ${CLAUDE_PLUGIN_ROOT}templates/verification-checklist-template.md