Information Architecture
In the context of technical writing, information architecture refers to the way the documentation is organized, structured, and labeled so that readers can navigate it efficiently and get the guidance they need.
It's hard to say whether you should start a documentation project by thinking of your information architecture or your content strategy.
In real life, you will probably switch from one to the other, and back again. Feel free to do the same in this playbook; the sections are meant to be readable independent from one another.
Topic-based authoring and book-based authoring have different audiences and require different approaches, so it's important to understand their particularities before making a choice.
At a structural level, there are only two types of documentation:
In this case, the user is expected to read through the material sequentially, from the start to the end, chapter by chapter. This type of documentation is generally delivered as physical, printed books or as PDFs.
The content is organized under the assumption that the reader is already familiar with the previous chapters, so jumping from one section to the other is not recommended. This makes them more suitable for products that fit a structured learning experience and where users do not need to quickly solve a specific problem.
That said, it doesn't mean that these user guides must be read from page 1 to page 100 in one go. Readers can navigate using the table of contents, indexes and references - and of course Ctrl+F is always available for digital formats.
Here, each page is a self-contained topic that can be read more or less out of sequence. This type of documentation is generally delivered in the form of an online help system.
Every Page is Page One, by Mark Baker, is the most well-known book about topic-based authoring.
Traditional, book-type manuals have fallen out of style these days, for good reason: modern users don't have time to read hundreds of pages to get their answers, and the search functionality in a PDF is inferior to that of a search engine.
However, book-style documentation is not completely gone; it is commonly used in regulated industries (such as aerospace), as well as for physical products (such as industrial equipment).
The rest of this page will focus on topic-based structure.
When planning out a topic-based documentation set, the first thing to decide content-wise is what types of topics you will create. Having a standardized set of topic types is essential for making your documentation easy to follow.
Two popular frameworks are described below; you can either adopt their principles as defined or modify them to suit your purposes.
Topic-based authoring was popularized in the 2000s through Darwin Information Typing Architecture (DITA), a framework developed by IBM and later standardized by OASIS.
DITA is an XML-based standard for modular documentation that structures content into three main topic types:
Of course, these three topic types do not fit every documentation set, but DITA allows specialization, which means that you can create new, customized information types based on existing DITA structures.
It is important to note that DITA encompasses two related, but different aspects:
- The conceptual definitions of the basic topic types
- The strict XML schemas used to technically validate the structure of the topics
You don't have to use DITA-the-XML-standard in order to use DITA-inspired-topic-types. In fact, many companies have defined their own topic types starting from the DITA ones, but write in Markdown or HTML rather than XML.
In the late 2010s, Daniele Procida developed Diátaxis, a framework that defines four topic types:
- Tutorial - teaches users through practical exercises.
- How-to guide - provides instructions for doing a task.
- Reference - contains technical details.
- Explanation - provides background and puts things in the bigger picture.
Because Diátaxis is just a concept, not an XML schema, it's easier to use in practice: it does not depend on a specific format or tooling and it can be interpreted as needed for each documentation project.
For a comparison between DITA and Diátaxis (and other frameworks like Information Mapping and The Good Docs Project), see this post by Tom Johnson.
Especially in large documentation sets, the navigation system is essential in helping users find the information they need.
As the majority of documentation is available nowadays in the form of an HTML-based help system, this is what this section focuses on.
These elements are typically included in modern online documentation:
Table of contents (TOC)
- Hierarchical, shows the structure of the documentation and helps users get a high-level view of the information available.
- Usually placed on the left side of the browser window.
- Sometimes a topic-level TOC is also included, usually on the right side.
- Should not have too many levels, otherwise it gets unwieldy.
Search
- A search bar is a must-have, in a visible location accessible from all pages.
- Can be enhanced with features like filters and suggestions.
- An AI chatbot can be used as an addition to the traditional search. It is not a good idea to replace the search completely, since AI agents serve a different use case. For example, if you are searching for an exact string, a search bar is a better choice than a chatbot.
Breadcrumbs
- Usually placed at the top of each topic.
- Help users understand where they are within the larger structure of the help system.
Responsive layout
- Ensures the documentation website is usable on all devices (desktop, tablet, mobile).
Contextual navigation
- "Related topics" sections or "next/previous" buttons to guide users to related content.
- Important, especially in complex help systems.
Consistency is important in navigation too. Make sure to use predictable icons, color schemes and labels to help users orient themselves in the documentation.
