Organizing Documentation

What this skill does

# 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**:

```markdown
| 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

```bash
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**:

```markdown
## 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:

```markdown
# 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:**
```bash
# 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`