2494 02 Documentation Guide 28037300

Documentation Strategy Guide

Framework for consistent documentation optimized for both humans and LLMs.

Core Principle

Documentation should make projects accessible to human contributors and LLM agents that need to understand, integrate with, or extend systems.

Two-Tier Documentation Model

Product docs: Full implementation detail, runbooks, schemas, testing procedures.

Shared packs: Concise LLM-facing summaries with cross-links to detailed docs.

Token Budgets by Page Type

Efficiency tips: Tables over prose (30-50% savings), bullets over paragraphs, omit articles in tables, use abbreviations (env, config, auth).

Directory Structure

Standard Project Structure

project-root/
├── README.md                    # Overview and quick start
├── docs/                        # Main documentation
│   ├── getting-started.md
│   ├── architecture.md
│   ├── api/
│   ├── guides/
│   └── troubleshooting/
└── examples/

Shared Docs Structure

docs/shared/
├── 01-company/                 # Brand, services, GTM
├── 02-products/                # Product packs
│   ├── 00-ecosystem-overview.md
│   └── XX-product-name/        # Per-product folder
├── 03-ai-enabling/             # Profiles, operations
└── 99-docs-maintenance/        # Utilities

Numbering rules:

• 00 reserved for overviews only
• Content starts at 01
• Files in shared packs: sparse numbering (10-, 20-) for insertions

Shared Pack Filenames

LLM-Ready Documentation

Required Header Block

---
product: [Product Name]
status: [Active | Beta | Deprecated | Planning]
last_updated: YYYY-MM-DD
source_of_truth: [path to detailed doc]
owner: [team]
token_estimate: [number]
---

Required Sections per Pack

1. Purpose - Problem solved, audience
2. System Context - Ecosystem position, components
3. Data Model - Key entities (table format)
4. Key Flows - Primary journeys (<5 steps each)
5. Integrations - Inbound/outbound connections
6. Auth Methods - Headers, tokens, signing
7. Environment Matrix - Domains per environment
8. Security Posture - Data handling, compliance
9. Decisions/Gaps - Priorities, limitations

Cross-Link Format

> **Full details:** [Page Title](relative/path/to/doc.md)

Place at section end, not inline. One per section maximum.

Content Location Decision

Cross-Product Integration

Integration Matrix Template

| Direction | Partner | Method | Data Exchanged |
|-----------|---------|--------|----------------|
| Inbound | Product A | Webhook | Assessment results |
| Outbound | Product B | API | Synthesized insights |

Shared Entity Template

### EntityName
Used by: Product A, Product B

| Field | Type | Description |
|-------|------|-------------|
| id | uuid | Unique identifier |
| name | string | Display name |

Integration Prompt Template (80-integration-prompt.md)

# Integration: [Product Name]

## To send data TO [Product]:
1. Auth: [method]
2. POST to `[endpoint]`
3. Payload: `{ "field": "value" }`

## To receive data FROM [Product]:
1. Register webhook at [endpoint]
2. Validate signature (HMAC-SHA256)
3. Handle events: [list]

## Gotchas:
- [Known issue or constraint]

Shared Pack Page Template

---
product: [Product Name]
status: Active
last_updated: YYYY-MM-DD
source_of_truth: [path]
owner: [team]
token_estimate: [number]
---

# [Topic]: [Product Name]

## Summary
[2-3 sentences maximum]

## [Content Section]

| Column 1 | Column 2 |
|----------|----------|
| data | data |

## Key Points
- Point 1
- Point 2

> **Full details:** [Doc Title](path/to/doc.md)

Duplication Control

Prevention: Run 99-docs-maintenance/check-shared-redundancy.sh after changes.

Handling redundant docs:

# [Title] - MOVED
**New location:** [Link](path/to/canonical.md)
**Archived:** YYYY-MM-DD

Then move to _archive/ preserving directory structure.

Writing Guidelines

Work Product Compression

Size Targets by Type

Token conversion: ~1.4 tokens per word for typical technical documentation.

Hard limits: Task Copilot validation enforces these limits. Exceeding hard limits results in rejection.

Compression Techniques

Table-first writing:

❌ Before (prose): "The authentication module supports three methods: JWT tokens for API access, OAuth2 for third-party integrations, and session cookies for web applications. JWT tokens expire after 1 hour. OAuth2 tokens expire after 30 days. Session cookies expire after 24 hours." (41 words, ~57 tokens)

✅ After (table):

| Auth Method | Use Case | Expiry |
|-------------|----------|--------|
| JWT | API access | 1 hour |
| OAuth2 | Third-party | 30 days |
| Session cookie | Web app | 24 hours |

(28 words, ~29 tokens - 49% savings)

Reference over duplication:

❌ Before: "The user registration flow consists of: 1. User submits email/password 2. System validates email format 3. System checks email uniqueness 4. System hashes password with bcrypt 5. System creates user record 6. System sends verification email 7. User clicks verification link 8. System activates account."

✅ After: "Implements standard registration flow (see `docs/auth/registration.md`). Key validations: email format, uniqueness check. Password hashing: bcrypt (cost=10)."

Attention-Optimized Structure

LLM attention degrades in middle sections. Structure work products to exploit attention curve:

High Attention Zones (70-100% attention):

• Start (first 200 tokens): Executive summary, key decisions, critical findings
• End (last 150 tokens): Action items, next steps, blocking issues

Low Attention Zone (30-50% attention):

• Middle: Supporting details, implementation notes, reference links

Standard work product structure:

# [Title]

## Summary (HIGH ATTENTION)
- Key decision: [Most important outcome]
- Impact: [Primary effect on system]
- Next: [Critical next action]

## Decisions (HIGH ATTENTION)
| Decision | Rationale | Impact |
|----------|-----------|--------|
| Choice A | Reason | Effect |

## Implementation Details (LOW ATTENTION)
[Supporting information, references, notes]

## Files Modified (LOW ATTENTION)
- `path/to/file.ts`

## Next Steps (HIGH ATTENTION)
1. [Critical action]
2. [Blocking dependency]

Heading Hierarchy for Importance

Use heading levels to signal importance to both humans and LLMs:

LLM attention prioritizes:

1. Higher-level headings (## > ### > ####)
2. First occurrence of each heading level
3. Sections with tables/structured data
4. Lists over prose

Checklists

New/Updated Feature

• Update detailed doc in docs/
• Update shared summary with cross-link
• Update last_updated in header
• Run redundancy check
• Verify cross-links resolve
• Update 40-integrations.md if needed

New Product Pack

• Create docs/shared/02-products/XX-name/
• Create 00-overview.md with header block
• Add minimum: overview, architecture, API, integrations
• Add to 00-ecosystem-overview.md
• Create 80-integration-prompt.md
• Verify total <4,000 tokens

Documentation Consolidation

• Run redundancy check script
• Classify duplicates (detail vs summary)
• Merge overlapping detail pages
• Replace shared duplicates with summaries + links
• Create redirect stubs for moved content
• Archive redundant files (never delete)

Quick Reference

Token Estimation

File Location Quick Test