Document Structure¶

Structure determines whether users find information or give up searching. A well-structured document guides readers to what they need. A poorly structured document buries information in walls of text.

Technical writing is not read like a novel. Users scan, search, and jump to relevant sections. Structure must support this behavior.

Why Structure Matters¶

Good structure serves multiple purposes:

Findability: Users locate information quickly through headings, navigation, and visual hierarchy.

Comprehension: Logical organization helps users understand relationships between concepts.

Scanability: Clear structure lets users assess content relevance without reading everything.

Maintenance: Well-organized documents are easier to update and extend.

Accessibility: Screen readers rely on heading structure to help users navigate.

Poor structure forces users to read linearly through irrelevant content to find what they need. Most will not bother.

Heading Hierarchy¶

Headings create document structure. They organize content and enable navigation.

Hierarchy Levels¶

Use headings hierarchically:

# Page Title (H1) - One per page
## Major Section (H2)
### Subsection (H3)
#### Sub-subsection (H4) - Use sparingly

Never skip levels. Do not jump from H2 to H4. Consistent hierarchy helps readers and assistive technology understand document structure.

Effective Headings¶

Good headings:

• Describe content accurately: "Configuring Authentication" not "Step 3"
• Use parallel structure: If one heading is a gerund, use gerunds consistently
• Front-load keywords: "Authentication Configuration" beats "How to Configure Authentication Settings for Your Application"
• Stand alone: Headings should make sense without reading surrounding text
• Enable scanning: Users should understand page content by reading headings alone

Weak headings:

Introduction Next Steps More Information Notes

Strong headings:

System Requirements Installing the Application Configuring User Authentication Troubleshooting Connection Errors

Heading Frequency¶

Break content with headings regularly. As a guideline:

• H2 every 300-500 words
• H3 as needed within sections
• No more than three paragraphs without a heading

Long unbroken text blocks discourage reading. Headings provide visual breaks and entry points.

Information Hierarchy¶

Beyond headings, content should flow from general to specific, important to supplementary.

The Inverted Pyramid¶

Journalism's inverted pyramid works for technical writing:

1. Lead with the essential information: What users most need to know
2. Follow with important details: Supporting information and context
3. End with supplementary material: Background, exceptions, advanced topics

Users who need only the basics can stop early. Users who need depth can continue.

Front-Loading¶

Place important information at the beginning of:

• Documents: Key information in the introduction
• Sections: Main point in the first paragraph
• Paragraphs: Topic sentence first
• Sentences: Subject and verb before qualifications

Front-loading respects scanning behavior. Users see the most important content first.

Progressive Disclosure¶

Not all information belongs at the same level. Progressive disclosure reveals complexity gradually:

• Essential information visible by default
• Additional detail available on demand (expandable sections, links)
• Advanced topics in separate documents

This approach serves users with different needs without overwhelming anyone.

Page Structure Patterns¶

Different content types benefit from different structures.

Conceptual Pages¶

Pages explaining concepts:

1. Introduction: What this is and why it matters
2. Core explanation: The main concept
3. Examples: Concrete illustrations
4. Related concepts: Links to connected topics

Task Pages (Procedures)¶

Pages describing how to do something:

1. Introduction: What this procedure accomplishes
2. Prerequisites: What users need before starting
3. Steps: Numbered, sequential instructions
4. Verification: How to confirm success
5. Troubleshooting: Common problems and solutions

Reference Pages¶

Pages providing lookup information:

1. Overview: Brief description of the reference content
2. Reference content: Organized for lookup (tables, alphabetical lists)
3. Examples: Usage examples
4. See also: Related references

Troubleshooting Pages¶

Pages helping users solve problems:

1. Symptoms: What users experience
2. Causes: Why this happens
3. Solutions: How to fix it
4. Prevention: How to avoid recurrence

Formatting for Scanability¶

Users scan before reading. Formatting should support scanning.

Lists¶

Lists are more scannable than paragraphs:

Paragraph (hard to scan):

The application supports user authentication, role-based access control, audit logging, and two-factor authentication.

List (easy to scan):

The application supports:

• User authentication
• Role-based access control
• Audit logging
• Two-factor authentication

Use lists for:

• Three or more related items
• Steps in a procedure
• Features, options, or requirements
• Anything users might need to reference

Tables¶

Tables organize complex information for comparison:

Use tables when information has consistent attributes across multiple items.

Code Blocks¶

Format code distinctively:

def authenticate(username, password):
    """Authenticate a user and return a token."""
    user = get_user(username)
    if user.verify_password(password):
        return generate_token(user)
    raise AuthenticationError("Invalid credentials")

Code blocks:

• Signal "this is code" visually
• Enable copy-paste
• Allow syntax highlighting
• Preserve formatting

Visual Hierarchy¶

Use visual elements to create hierarchy:

• Bold for emphasis and key terms
• Italic for introducing terms or subtle emphasis
• Monospace for code, commands, file paths

• Blockquotes for callouts or quoted material

Consistent visual hierarchy helps users understand content organization.

Navigation Elements¶

Structure includes navigation aids that help users move through content.

Tables of Contents¶

For longer documents, include a table of contents:

• Generated from headings
• Linked for quick navigation
• Collapsed on mobile for space

Most documentation platforms generate these automatically.

Breadcrumbs¶

Breadcrumbs show location in site hierarchy:

Home > Fundamentals > Document Structure

They help users understand context and navigate to parent sections.

Cross-References¶

Link related content:

• Prerequisites ("Before you begin, see Installation")
• Related topics ("For authentication options, see Security Configuration")
• Deep dives ("For advanced options, see Advanced Configuration")

Cross-references connect information and help users find what they need.

Next/Previous Navigation¶

Sequential content benefits from navigation links:

Previous: Active vs. Passive Voice

Next: Using Visuals Effectively

This helps users work through content systematically.

Structuring Long Documents¶

Long documents require additional organization strategies.

Chunking¶

Break long content into manageable chunks:

• Each section should cover one topic
• Aim for sections that fit on one or two screens
• Use headings to introduce each chunk

Chunking prevents overwhelming users and improves comprehension.

Multiple Pages vs. Single Page¶

Consider whether content works better as:

Single long page:

• Content users read sequentially
• Search needs to find terms anywhere
• Users might print the document

Multiple pages:

• Distinct topics users access independently
• Different audiences for different sections
• Very long content (over 3,000 words)

Most documentation works better as multiple focused pages.

Landing Pages¶

Section landing pages provide overview and navigation:

• Brief description of the section
• List of pages with descriptions
• Suggested reading order if applicable

Landing pages help users orient themselves in large documentation sets.

Common Structural Problems¶

Wall of Text¶

Long paragraphs without breaks overwhelm users.

Problem:

The application configuration file contains settings for database connection, authentication, logging, and performance tuning. The database section includes connection string, pool size, and timeout settings. Authentication settings control user verification, session duration, and password policies. Logging configuration determines log levels, output destinations, and rotation policies. Performance settings affect caching, connection pooling, and request handling.

Solution: Break into headed sections with lists:

Configuration Sections¶

The configuration file contains:

• Database: Connection string, pool size, timeout
• Authentication: User verification, sessions, passwords
• Logging: Log levels, outputs, rotation
• Performance: Caching, pooling, request handling

Buried Information¶

Important information hidden deep in documents goes unread.

If users frequently miss critical information, it is a structure problem. Move important content earlier or make it more prominent.

Inconsistent Structure¶

Parallel content should follow parallel structure. If one API endpoint is documented with Description, Parameters, Response, Examples—all endpoints should follow this pattern.

Inconsistency forces users to relearn structure for each section.

Missing Signposts¶

Without clear headings and introductions, users cannot orient themselves.

Every section should answer: "What is this, and why should I read it?"

Summary¶

Document structure determines whether users find information. Effective structure uses:

• Clear heading hierarchy: Organized, descriptive, parallel
• Information hierarchy: Important content first
• Scannable formatting: Lists, tables, code blocks
• Navigation aids: TOC, breadcrumbs, cross-references
• Appropriate page organization: Patterns suited to content type

Structure is not decoration. It is fundamental to documentation usability.

Next: Using Visuals Effectively covers when and how to use diagrams, screenshots, and other visual elements.