bee:documentation-structure

Documentation Structure

Good structure helps users find what they need quickly. Organize content by user tasks and mental models, not by internal system organization.

Content Hierarchy

Documentation/
├── Welcome/              # Entry point, product overview
├── Getting Started/      # First steps, quick wins
├── Guides/              # Task-oriented documentation
│   ├── Understanding X   # Conceptual
│   ├── Use Cases        # Real-world scenarios
│   └── Best Practices   # Recommendations
├── API Reference/       # Technical reference
│   ├── Introduction     # API overview
│   └── Endpoints/       # Per-resource documentation
└── Updates/             # Changelog, versioning

---

Page Structure Patterns

Page Type	Structure
Overview	Brief description → "In this section you will find:" → Linked list of child pages
Conceptual	Lead paragraph → Key characteristics (bullets) → How it works → Subtopics with --- dividers → Related concepts
Task-Oriented	Brief context → Prerequisites → Numbered steps → Verification → Next steps

---

Section Dividers

Use --- between major sections for visual separation.

When to use:

• Between major topic changes
• Before "Related" or "Next steps" sections
• After introductory content
• Before prerequisites in guides

Don't overuse: Not every heading needs a divider.

---

Navigation Patterns

Pattern	Usage
Breadcrumb	Show hierarchy: Guides > Core Entities > Accounts
Prev/Next	Connect sequential content: [Previous: Assets] | [Next: Portfolios]
On-this-page	For long pages, show section links at top

---

Information Density

Scannable content:

1. Lead with key point in each section
2. Use bullet points for 3+ items
3. Use tables for comparing options
4. Use headings every 2-3 paragraphs
5. Bold key terms on first use

Progressive disclosure:

• Essential info (80% of users need) first
• Advanced configuration in separate section
• Edge cases and rare scenarios last

---

Tables vs Lists

Use tables when: Comparing items across same attributes, showing structured data (API fields), displaying options with consistent properties

Use lists when: Items don't have comparable attributes, sequence matters (steps), items have varying detail levels

---

Code Examples Placement

Type	When
Inline code	Short references: "Set the assetCode field..."
Code blocks	Complete, runnable examples

Rules:

1. Show example immediately after explaining it
2. Keep examples minimal but complete
3. Use realistic data (not "foo", "bar")
4. Show both request and response for API docs

---

Cross-Linking Strategy

• Link first mention of a concept in each section
• Don't over-link – once per section is enough
• Link destinations: Concept → conceptual docs, API action → endpoint, "Learn more" → deeper dive

---

Page Length Guidelines

Page Type	Target	Reasoning
Overview	1-2 screens	Quick orientation
Concept	2-4 screens	Thorough explanation
How-to	1-3 screens	Task completion
API endpoint	2-3 screens	Complete reference
Best practices	3-5 screens	Multiple recommendations

If >5 screens, consider splitting.

---

Quality Checklist

• Content organized by user task, not system structure
• Overview pages link to all child content
• Section dividers separate major topics
• Headings create scannable structure
• Tables used for comparable items
• Code examples follow explanations
• Cross-links connect related content
• Page length appropriate for type
• Navigation connects sequential content

---

Standards Loading (MANDATORY)

Before planning documentation structure:

1. Understand content types - What documents will exist (conceptual, how-to, API reference)
2. Load writing skills - bee:writing-functional-docs and bee:writing-api-docs
3. Review existing structure - Understand current documentation hierarchy

HARD GATE: CANNOT reorganize documentation without understanding content and audience.

---

Blocker Criteria - STOP and Report

Condition	Decision	Action
Content inventory incomplete	STOP	Report: "Need complete list of documentation topics"
User tasks undefined	STOP	Report: "Need user task list to organize around"
Information architecture undefined	STOP	Report: "Need IA decisions before structuring"
Navigation requirements unclear	STOP	Report: "Need navigation pattern decisions"

Cannot Be Overridden

These requirements are NON-NEGOTIABLE:

• MUST organize by user tasks (not system structure)
• MUST include overview pages that link to children
• MUST use section dividers (---) between major topics
• MUST keep page length appropriate for document type
• CANNOT nest deeper than H3 without good reason
• CANNOT create orphan pages (must be linked)

---

Severity Calibration

Severity	Criteria	Examples
CRITICAL	Completely disorganized, no navigation	No hierarchy, orphan pages everywhere
HIGH	Organized by system, not user tasks	"Database tables" instead of "Managing accounts"
MEDIUM	Missing links, poor scannability	No cross-links, walls of text
LOW	Structure works but could be optimized	Could improve navigation, add dividers

---

Pressure Resistance

User Says	Your Response
"Organize by our system components"	"MUST organize by user tasks. System structure ≠ mental model. I'll structure around what users do."
"One long page is fine"	"Long pages overwhelm users. MUST split by document type guidelines. I'll organize appropriately."
"Skip the overview pages"	"Overview pages are REQUIRED for navigation. I'll create overview pages linking to children."
"Cross-links are extra work"	"Cross-links enable discovery. MUST connect related content. I'll add appropriate links."
"Flat structure is simpler"	"Flat structure makes finding content harder. MUST use appropriate hierarchy."

---

Anti-Rationalization Table

Rationalization	Why It's WRONG	Required Action
"Mirrors our codebase structure"	Users don't know your codebase	MUST organize by user tasks
"Everything on one page is convenient"	Convenience for whom? Not users	Split per page length guidelines
"Deep nesting shows thoroughness"	Deep nesting hides content	Keep hierarchy shallow (H3 max)
"Users will search anyway"	Search supplements, not replaces structure	MUST provide clear navigation
"Links can be added later"	Orphan pages are lost pages	Add links during creation
"Structure is aesthetic, not functional"	Structure IS functionality	Structure enables findability

---

When This Skill is Not Needed

Signs that documentation structure is already correct:

• Content organized around user tasks and goals
• Clear hierarchy with appropriate depth
• Overview pages link to all child content
• Section dividers separate major topics
• Navigation connects sequential content
• Cross-links connect related topics
• Page lengths appropriate for document type
• No orphan pages

If all above are true: Structure is correct, no reorganization needed.