Welcome back to our series on technical writing. In our last lesson, we focused on ensuring consistency. Today, we'll build on that by organizing our content with structure.

Imagine you're trying to assemble furniture using instructions that are just one long paragraph. The list of parts is mixed in with the steps, and a critical warning is buried at the very end. You'd probably get frustrated and give up! This is what happens when documentation lacks structure, and it can be a major roadblock for your users.

In technical documentation, structure is the skeleton that holds everything together. It creates a logical path for the reader to follow, making complex information digestible and easy to navigate. When your documentation is well-structured, readers can find what they need quickly, whether they're looking for a quick answer or a detailed walkthrough.

Why structure matters in docs

• Enhances readability: A logical flow from one section to the next helps readers process and understand complex information without feeling overwhelmed.
• Improves findability: Good structure acts like a map. Readers can scan headings and lists to pinpoint the exact information they need, which is crucial since most users skim documents for answers.
• Reduces cognitive load: When content is organized predictably, readers don’t have to waste mental energy figuring out where to look. They can focus on learning and applying the information.
• Helps in comprehension: Breaking down information into smaller, well-defined chunks (like steps, lists, or tables) makes it easier for the brain to absorb and retain.
• Empowers AI and Chatbots: With the growing use of AI summaries and agents, a clear structure is the secret sauce! AI models can parse well-structured content more effectively, allowing them to provide more accurate summaries and direct answers to user’s questions.

The pillars of structure

Structure can be broken down into four main areas:

• Hierarchical headings
• Logical flow
• Information types
• Visual elements

1. Hierarchical headings

How do you show which ideas are major topics and which are supporting details? Use a clear hierarchy of headings (like H1, H2, H3). Your main page title should be your only H1, with H2s for major sections and H3s for subsections within them. This creates a scannable outline of your document.

Tip: Before you start writing, create an outline using only your headings. If you can understand the document's main points just by reading the outline, your structure is on the right track.

2. Logical flow

The order of your content matters. A tutorial should follow a chronological order, with the right steps in the right order. A conceptual guide should move from a high-level overview to more specific details as you get more deeper into the guide. A troubleshooting guide should state the problem first, then walk you through the solution. Arranging information in the most intuitive way for the reader’s goal will result in the best flow.

3. Information types

Don't just write paragraphs. Use different formats to present different types of information. This breaks up the text and makes it easier to scan.

• Use numbered lists for sequential instructions.
• Use bullet points for non-sequential lists, like prerequisites or options.
• Use tables to present structured data, like configuration parameters or feature comparisons.
• Highlight tips and notes on the page so that the reader doesn’t miss them. 

Tip: Provide code samples with realistic example data so that developers do not have to plow through API reference and Integration docs to get the right details.

Code Samples Example:

Before: Unstructured example

A developer looking at this string would have to spend time parsing it manually to understand the relationship between the customer, the payment method, and the metadata. It's difficult to read and even harder to debug if something goes wrong.

charge_details = {'amount': 990, 'currency': 'usd', 'customer_id': 'cus_Hn9s73TsbV', 'metadata': {'order_id': 'a5b2-9z7d'}}

After: Structured example

This version uses indentation and comments to create a clear structure. A developer can immediately see the main components of the request: payment details, source, description, shipping information, and internal metadata. The comments explain the purpose of each object, reducing the cognitive load required to understand the code.

charge_details = {

    # Core payment information

    'amount': 990,       # In cents

    'currency': 'usd',

    'customer_id': 'cus_Hn9s73TsbV',

‍

    # Internal tracking data

    'metadata': {

        'order_id': 'a5b2-9z7d'

    }

}

4. Visual elements

How do you highlight different types of content? Just as you use bold for UI elements or code blocks for code, you should use visual elements consistently to structure the page. Screenshots, diagrams, and call-out boxes (like for notes or warnings) act as signposts that help readers visually parse the content and quickly find what's relevant to them. Using consistent fonts, color schemes, logos, etc also make it easy for the reader to scan your documentation.

Actionable tip: create a template

The best way to ensure structure is to create templates for your common document types. This is like a style guide, but for layout and organization. A template provides a ready-made skeleton, so you just need to fill in the content. This ensures every How-to guide or Troubleshooting article across your organization has the same predictable, user-friendly structure.

For example, a template for a How-to Guide might look like this:

• Title: Start with a gerund, for example, Configuring the SardineAI Dashboard.
• Introduction: 1-2 sentences explaining what the user will achieve.
• Prerequisites: A bulleted list of what the user needs before starting, such as:
  
  • API keys with the correct permissions.
  • Specific software versions installed (for example, Node.js v18+).
  • An active sandbox account.
  • Completion of a prerequisite guide (for example, Generating your API credentials).
• Procedure: A numbered list of steps in chronological order. Adding images or screenshots would be helpful here. Include:
  
  • Complete, runnable API request examples for each step.
  • Example API responses showing what a successful outcome looks like.
  • Callouts for optional parameters versus required ones.
• Result: A short description of the successful outcome, with:
  
  • Screenshots of the resulting UI change.
  • Confirmation messages or success codes the user should expect.
• Next steps or References: Optional: Links to related articles or tasks.

Tip: Store your templates in a shared team space like a wiki or a repository or like me, in Notion. This makes it easy for everyone to use them and promotes structural consistency across all your documentation!

Further reading and resources

• Free Technical Document Templates
• Technical Writing One - Documents
• Klariti - Technical Writing Templates

By focusing on structure from the outset, you'll be able to create documentation that is not only clear and consistent but also incredibly easy for your users to follow.

I hope these tips were helpful to you. Think about what kind of template would be most useful for your team and start building it today!