Chapter 10: Organizing Documentation

Chapter 9

Have you ever wasted hours searching through disorganized documentation?

Poorly structured documentation costs the team's time, frustrates users, and undermines trust in your product. 

This chapter shows you how to avoid these pitfalls by designing documentation that guides users to answers intuitively.

Organizing Documentation focuses on how to structure your documentation to make it easy for users to find what they need. It emphasizes that well-organized documentation helps readers build a mental map of your content. 

How to Organize Your Documentation Effectively

The key is to make your documentation logical and easy to navigate, as clear organization is essential for scaling up documentation as more content is published.

1. Help Readers Find Their Way

Users scan documentation, looking for clues. You can help them through the following ways:

a. Use clear site navigation to show how your content is organized. There are 3 basic ways to organize content.

Sequences: A linear order, like steps in a tutorial or an alphabetical list

Hierarchies: A tree-like structure, from broad topics to specific details

Webs: Interconnected pages, like Wikipedia, where users can jump between related topics

Most sites use a combination of these. For example, a landing page might be hierarchical, with each section containing sequential steps.

b. Create effective landing pages that act as signposts, guiding users to the right content. Keep them short, scannable, and focused on user needs. Highlight the most relevant information.

c. Provide navigation cues that show users where they are in the documentation and how to get to other relevant pages. These include breadcrumbs which show the path to a page, Side navigation to display the site's structure, Labels and metadata to give essential information about the document, Prerequisites, next steps, and escape hatches that link to alternative pages if the user is in the wrong page.

2. Structure Your Documentation

This involves:

a. Assessing existing content: Make a list of all your documentation, and evaluate each page for usefulness and accuracy. Identify any content gaps (missing information users need).

b. Outlining a new information architecture: Plan how your content should be organized. Consider the mental model your users have. Aim for consistent patterns and structures. Use techniques like card sorting (writing each page on a card and rearranging them) to experiment with different structures. Make sure common tasks have clear starting points and well-defined steps.

c. Migrating to the new architecture: Move content into the new structure. Use a checklist to ensure landing pages are clear, content types are consistent, page data (titles, headers) is descriptive, navigation cues are in place, and redirects are set up for old URLs. Document your information architecture (decisions made, user research, patterns used) to maintain consistency.

3. Maintain Your Information Architecture

When adding new content, ask: Is it clear where this content belongs? Are adjustments needed to the information architecture? Does it affect the home page or landing pages? Regularly verify users' mental models and update the architecture as your product and documentation grow.

To recap, effective documentation organization hinges on three pillars:

1. Planning: Align structures with user needs.
2. Execution: Use navigation tools (breadcrumbs, hierarchies) to build mental maps.
3. Maintenance: Adapt as your product and audience grow.

Thank You for reading.