Document Structure Skill

Overview

This skill provides expertise in organizing complex technical documentation with clear hierarchies, logical flow, and intuitive navigation for R&D audiences. It ensures documents are scannable, navigable, and appropriately structured for their purpose and audience.

Key Capabilities

Information Architecture

• Create logical document hierarchies (H1-H6 heading structure)
• Organize content from high-level concepts to detailed implementations
• Group related topics and create clear content sections
• Design table of contents and navigation structures
• Implement progressive disclosure patterns
• Balance depth with readability

Structural Thinking

• Identify document purpose and optimize structure accordingly
• Recognize when content needs splitting vs. consolidation
• Apply consistent patterns across document families
• Design for both sequential reading and random access

Document Types and Structures

Strategic Documents

Executive Summary Structure:

# [Title]

## Executive Summary
[2-3 paragraph overview - can stand alone]

## Current Situation
[Brief context setting]

## Recommended Action
[Clear recommendation]

## Expected Outcomes
[Quantified benefits]

## Request
[Specific ask: approval, resources, decision]

Business Case Structure:

# Business Case: [Title]

## Executive Summary
## Problem Statement
## Proposed Solution
## Options Analysis
### Option 1: [Name]
### Option 2: [Name]
### Option 3: [Name]
## Recommendation
## Financial Analysis
## Risk Assessment
## Implementation Plan
## Appendices

Technical Documents

Architecture Guide Structure:

# [System] Architecture

## Overview
### Purpose
### Scope
### Key Decisions

## System Context
[Where this fits in the larger ecosystem]

## Component Architecture
### Component 1
### Component 2
[...]

## Data Architecture
### Data Models
### Data Flow

## Integration Points
### External Systems
### APIs

## Security Architecture
## Deployment Architecture
## Appendices

API Reference Structure:

# [API Name] Reference

## Overview
## Authentication
## Base URL and Versioning
## Request/Response Formats

## Endpoints

### [Resource] Endpoints
#### GET /resource
#### POST /resource
#### GET /resource/{id}
[...]

## Error Handling
### Error Codes
### Error Response Format

## Rate Limits
## SDKs and Examples
## Changelog

Process Documents

SOP Structure:

# [Process Name] SOP

## Purpose
## Scope
## Roles and Responsibilities

## Prerequisites
- [ ] [Prerequisite 1]
- [ ] [Prerequisite 2]

## Procedure

### Step 1: [Action]
[Detailed instructions]

### Step 2: [Action]
[Detailed instructions]

[...]

## Verification
## Exception Handling
## Related Documents
## Revision History

Reference Documents

Structural Patterns

Pattern 1: Getting Started Progression

Best for: Tutorials, onboarding, learning content

1. Overview (What is it? Why care?)
2. Prerequisites (What do I need?)
3. Quick Start (Minimal viable first step)
4. Core Concepts (Essential understanding)
5. Step-by-Step Tutorial (Guided practice)
6. Common Issues & Troubleshooting (When things go wrong)
7. Next Steps (Where to go from here)

Pattern 2: Problem-Solution-Benefit

Best for: Proposals, recommendations, change requests

1. Context & Need (Why are we here?)
2. Problem Statement (What's wrong?)
3. Proposed Solution (What do we do?)
4. Benefits (Why this solution?)
5. Alternatives Considered (What else we looked at)
6. Implementation (How do we do it?)
7. Success Criteria (How do we know it worked?)

Pattern 3: Reference Hierarchy

Best for: Technical specifications, configuration guides

1. Purpose & Scope
2. Quick Reference (Most common items)
3. Detailed Reference
   3.1 Category A
       3.1.1 Item 1
       3.1.2 Item 2
   3.2 Category B
       [...]
4. Examples
5. Related Resources

Pattern 4: Decision Support

Best for: Comparison documents, evaluation frameworks

1. Context & Decision Needed
2. Evaluation Criteria
3. Options Overview (Summary table)
4. Detailed Analysis
   4.1 Option 1: [Name]
   4.2 Option 2: [Name]
   [...]
5. Comparison Matrix
6. Recommendation
7. Implementation Path

Pattern 5: Operational Runbook

Best for: Procedures, incident response, maintenance

1. Purpose (When to use this runbook)
2. Prerequisites (Required access, tools)
3. Procedure
   3.1 Step 1 (with verification)
   3.2 Step 2 (with verification)
   [...]
4. Rollback Procedure
5. Troubleshooting
6. Escalation

Heading Hierarchy Best Practices

Level Usage

Heading Rules

Do:

• Use action-oriented headings for procedures: "Configure the API"
• Use question headings for FAQs: "How do I reset my password?"
• Keep headings parallel in structure
• Make headings scannable and descriptive
• Limit to 8 words or fewer

Don't:

• Skip heading levels (H2 → H4)
• Use headings for formatting/emphasis
• Start multiple headings with same word
• Use vague headings like "Overview" alone
• End headings with punctuation

Heading Quality Test

For each heading, ask:

1. Specific: Does it tell what this section contains?
2. Unique: Is it distinct from other headings?
3. Scannable: Can readers find what they need by scanning?
4. Parallel: Does it match sibling heading structure?

Content Organization

Information Flow Patterns

Inverted Pyramid:

• Most important information first
• Supporting details follow
• Background/context last
• Best for: Executive content, summaries

Narrative Flow:

• Beginning → Middle → End
• Builds understanding progressively
• Best for: Tutorials, explanations

Reference Organization:

• Alphabetical, categorical, or hierarchical
• No assumed reading order
• Best for: API docs, glossaries, configurations

Section Length Guidelines

Chunking Content

3-5-7 Rule:

• 3-5 major sections per document
• 5-7 subsections per major section
• 3-7 items per list

When to Use Different Formats:

Navigation Design

Table of Contents

When to Include:

• Documents >5 pages
• Documents with >5 major sections
• Reference documents of any length

TOC Format:

## Table of Contents

1. [Section Name](#section-name)
   1.1. [Subsection](#subsection)
   1.2. [Subsection](#subsection)
2. [Section Name](#section-name)
   [...]

Cross-References

Internal Links:

See [Authentication](#authentication) for details.
Refer to the [Configuration Guide](./configuration.md).

External References:

For more information, see [Official Documentation](https://docs.example.com).

Navigation Aids

For Long Documents:

• Back to top links after major sections
• Breadcrumb-style context in headers
• Mini-TOC at section start for complex sections

For Document Sets:

• Index or landing page
• Consistent navigation elements
• Clear document type indicators

Templates

Universal Section Template

## [Section Title] (Clear, Action-Oriented)

**Context:** [Brief explanation of why this matters - 1-2 sentences]

### [Subsection if needed]

[Main content: explanation, steps, or information]

**Key Points:**
- [Main point 1]
- [Main point 2]
- [Main point 3]

[Tables, code blocks, or lists as appropriate]

**Considerations:**
- [Important note 1]
- [Important note 2]

**Related:** [Links to related sections or documents]

Document Metadata Template

---
title: [Document Title]
version: [X.Y.Z]
last_updated: [YYYY-MM-DD]
author: [Name/Agent]
status: [Draft|Review|Approved|Published]
audience: [Primary audience]
---

Quality Checklist

Structure Quality

• Single H1 (document title only)
• No skipped heading levels
• Logical section flow
• Parallel heading structure
• Appropriate section lengths

Navigation Quality

• TOC for long documents
• Working internal links
• Clear cross-references
• Easy to scan headings

Content Organization

• Most important information prominent
• Related information grouped
• Progressive disclosure used
• Appropriate format for content type

Accessibility

• Descriptive link text (not "click here")
• Tables have headers
• Lists used appropriately
• Clear visual hierarchy

Evaluation Criteria

Success Metrics

• Findability: Users locate information in <30 seconds
• Comprehension: Single read understanding >90%
• Completion: Users finish relevant sections
• Navigation: <3 clicks to any content
• Maintenance: Easy to update without restructuring

Related Skills

• #technical-writing - Content quality within the structure
• #data-visualization - Visual elements within documents
• #ai-terminology - Consistent terminology
• #document-structure is foundational for all documentation skills