Part 1: Learn The Different Types Of Technical Documentation
This is Part 1 of a five part tutorial on technical writing. To learn why this tutorial is the way it is, and why technical writing in general, see the Intro post.
KEY TERMS
In the same way the term “books” includes fiction, nonfiction, and biographies as genres, the term “technical documentation” includes many different content types. But what sets technical documentation apart from books are reader traits. These traits are a result of what the reader does as they read technical documentation – they use the app.
Behavior: How does the reader consume the content? For example, do they generally read the content in sequence? Or do they scan the TOC? Readers may scan the TOC to see which topics are in the guide, or jump to a section that meets their needs.
Patience: Is the reader generally impatient or patient as they’re reading the content? For example, a reader may have more patience with a getting started guide versus a reference guide.
Experience: What’s the reader’s experience level with your app? For example, a reader using a getting started guide will have little to no experience with your app.
Goal: What does the reader hope to achieve after reading the content?
This table lists the most common types of technical documentation; notice the reader traits for each. Also, notice how most content types are user guides. It doesn’t matter if the app is an internal app, an external app, or even just for yourself. The most helpful technical documentation focuses on what the user needs to be successful with the app.
Celebrated authors often advise writers to “read as much as you can³”, so you shouldn’t be surprised why I think new – and experienced – technical writers should read technical documentation as much as they can. To help you, I’ve gathered examples for each content type. The linked examples are from well-known products and include my notes on what works well and what doesn’t for me as a reader.
Info: I’m certain the companies who provide these products have dedicated teams who research the best look, feel, and content for their sites. But this doesn’t mean that the structure or the content can’t be changed per user feedback. User feedback is essential because it keeps sites relevant and helpful.
Getting started guide
Tutorial
How-to guide
Explanation guide
Reference guide
Troubleshooting guide
As a new user, troubleshooting guides are one of the first things I look for when I’m learning something new. They help me understand what may go wrong, and often lead me to other guides I wouldn’t have known to look for. I wish more sites included them and made them easy to find – especially if the search isn’t helpful.
Onboarding guides
Onboarding guides are very specific to teams so the content structure varies quite a bit. Here are a few resources:
Runbooks
Runbooks are also very specific to teams. And some, like disaster recovery runbooks, need to contain more sections and content because they’re printed and stored safely. Here are a few resources:
Try it out
Choose a single app you’d like to document. Remember, in this series, a component library that’s offered in Figma and in React are two different apps.
Determine the target audience for your app.
Select a content type for your app – just one. 🙂 If you’re not sure which content type you need for your app, think of yourself as a user then fill in these statements. The statement with the most answers is the content type you should probably draft first.
As a user, I want to get started with… → Get started
As a user, I want to… → How-to
As a user, I want to learn about… → Tutorial
As a user, I want to learn how to… → Tutorial
As a user, I want to understand… → Explanation
As a user, I want an introduction to… → Explanation
As a user, I want specific information on… → Reference
As a user, I want to fix… → Troubleshooting
Using one of the provided examples for your content type:
What works well for you as a reader?
Are the titles and subtitles helpful?
Could you use some of the headings in your content?
Do you like where the code examples and images are used?
What doesn’t work well for you as a reader?
Is the content difficult to scan? Overwhelming?
Lack of steps? Or, too many steps per task?
Up next
Part 2: Use good headings for structure and scanning. Creating good headings is not easy. The cheat sheets introduced in this part do most of the work for you. ⭐
¹ These content types, definitions, and guidelines use the Diataxis documentation framework theory as a foundation.
² In a perfect world, reference guides would be auto-generated from the documentation in the source code. In a not-so-perfect world, you may be asked to write reference guides from scratch because the source code contains no documentation, or the documentation in the source code reads like source code… This has happened to me more than once.
³ See If you want to be a writer, you have to be a reader first from Austin Kleon. My favorite blog on writing and creativity.
⁴ Overlinking decreases readability and comprehension, this is also known as “overlinking crisis”. For details, see Overlink crisis | Wikipedia and Removing Inline Links to Increase Readability | I'd Rather Be Writing.
⁵ I cannot stress how much I love this structure. In my experience, it’s very rare for API documentation sites to provide this type of foresight for their users. For what it’s worth, I created a similar guide for internal APIs at another startup and the developers, even business managers, really appreciated it.
⁶ When everything you need to know about a single topic is provided on one page, the user experience echoes the writing for the web philosophy known as “every page is page one”. I believe this philosophy works well only for explanation guides because of the reader’s goal: “I have in-depth context of the app so I can get the most out of it.” The philosophy was popularized by Mark Baker’s book Every Page Is Page One and also reviewed by Tom Johnson, a senior technical writer at Google. His blog has a very large following in the technical writing community.
⁷ I’m not sure why, but many API documentation sites don’t describe the returned payload. As a developer, I would find this maddening, especially if the payload contains nested objects with attributes that are alike, but serve different purposes. If you can help me understand this structure, please reach out!