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 this tutorial, an app represents a single piece of software that’s provided for others to use. This could be a mobile app, a web app, a microservice, a database, an API, a Figma component library, a React component library, a script, and so forth.
-
The group of people who are most likely to use the app. For example, if the app is an API, the target audience is likely to be only developers. Whereas the target audience for a Figma component library is designers.
-
Any piece of writing that includes technical writing.
-
Abbreviation for table of contents.
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.
| Type1 | Description | Reader traits |
|---|---|---|
| Getting started guide | A user guide that sets up and starts with your app. | Behavior: In sequence
Patience: Patient Experience: None to Basic Goal: “I started working with the app and feel comfortable using it.” |
| Tutorial | A step-by-step user guide that demos a use case or concept with your app.
A tutorial combines multiple tasks to achieve a specific goal. |
Behavior: In sequence
Patience: Patient Experience: Basic to Experienced Goal: “I learned a new skill with the app and have confidence with it.” |
| How-to guide | A step-by-step user guide that completes a real-world task with your app.
How-to guides are limited to a single task and don’t detail concepts, but they often link to explanation guides. |
Behavior: In sequence
Patience: Patient Experience: Basic to Experienced Goal: “I completed the task successfully.” |
| Explanation guide | A user guide that clarifies a single topic in your app.
Explanation guides don’t provide instructions, but they do link to how-tos and tutorials, or even a getting started guide. |
Behavior: In sequence or scan TOC
Patience: Patient Experience: Basic to Experienced Goal: “I have in-depth context of the app so I can get the most out of it.” |
| Reference guide2 | A user guide with technical facts or specifications about a software element in your app. | Behavior: Scan TOC
Patience: Impatient Experience: Basic to Experienced Goal: “I found the information I needed quickly; I’m back to working with the app.” |
| Troubleshooting guide | A user guide with solutions to problems with your app. | Behavior: Scan TOC
Patience: Impatient Experience: Basic to Experienced Goal: “I found a solution for my problem with the app, and solved it quickly.” |
| Onboarding guide | A handbook for a new teammate.
Onboarding guides help new teammates gain a broader understanding of the team’s systems, processes etc. |
Behavior: In sequence
Patience: Patient Experience: None to Basic Goal: “I completed the necessary setup and understand my team’s systems.” |
| Runbook | A step-by-step team guide that completes a common task or procedure. | Behavior: In sequence or scan TOC
Patience: Patient or Impatient Experience: Basic to Experienced Goal: “I completed the task or procedure successfully.” |
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
- Getting started guide:
- A user guide that sets up and starts with your app.
- Reader’s goal:
- “I started working with the app and feel comfortable using it.”
| Example | What works well? | What doesn’t work well? |
|---|---|---|
| Mailchimp | Things to know section; really helpful as a first-time user.
Clear steps; each with a single task. Some tasks include sub-steps when necessary – really helpful! Next step section; explains the purpose and use case for each linked guide. Even links to developer docs if a reader happens to be a developer. |
Task roadmap heading; it feels redundant when I can see the tasks in the content navigation. Also, “roadmap” in a heading threw me off when this is get started guide.
Some images feel unnecessary; like the image of the “Begin” button. |
| React.dev | Subtitle and You will learn box; right away I know what I’ll gain from the guide.
Simple structure: headings, a brief paragraph, code, ordered tasks or diagrams. My focus remains on the content. Live code editor. Next steps section. White space 🤩; the site has really nice padding and spacing. |
Nothing! |
| Cockroach DB | Each task has fewer than five steps – as a new user, I really appreciate this.
Learn more section. White space 🤩; the site has really nice padding and spacing. |
Subtitle is concise, but the goal feels abstract. In other words, why would I want to create a CockroachDB Serverless cluster for my app in the first place? No context after task headings. As a new user, I need more context, even a short sentence would help. |
| Chrome Developers |
Video that shows a live-demo of DevTools in Chrome. Easy-to-scan TOC and content; sections include images for each panel. |
Overlinking4. The Get started section makes me wonder if I'm on the wrong page because it has so many links. It also states, “If you're a more experienced web developer…” |
Tutorial
- Tutorial:
- A step-by-step user guide that demos a use case or concept with your app. A tutorial combines multiple tasks to achieve a specific goal.
- Reader’s goal:
- “I learned a new skill with the app and have confidence with it.”
| Example | What works well? | What doesn’t work well? |
|---|---|---|
| Build adaptive apps with Jetpack Compose | Google | Introduction page that includes What you’ll learn, What you’ll need, and What you’ll build section – right away I know what this tutorial is about.
The Adaptability section; it includes a definition for “adaptive” in plain language. This is really nice in a tutorial because I don’t have to search for definitions. The Get set up section; I have the option to download the sample app. The section also includes the Explore the start code subsection – this is so nice, and rare in tutorials. Each section in the tutorial addresses a single topic and includes the expected output 🤩; I feel reassured and not overwhelmed. Congratulations section; scanning this section in the left nav reassured me as a novice user. |
Nothing! |
| Create API walkthroughs | Typeform | The subtitle; right away I know what I’ll be doing as I follow the tutorial.
Love – love – how this tutorial provides common use cases with different endpoints5. Simple structure: headings, a brief paragraph, code, ordered tasks or diagrams. My focus remains on the content. Ready to do more? section; love the encouraging title. |
Very little! I wish the guide had a TOC though to make the content easier to scan. |
| Drawing Paths and Shapes — SwiftUI Tutorials | Apple |
Title and intro that’s to the point. Right away, I know the use case for the tutorial, what I’ll be building, estimated time, and demo files. Clear sections, each with a major action and substeps. Check Your Understanding quiz. 🤩 |
One section had nine substeps; this seemed a lot to me, but perhaps it was necessary. All in all, these tutorials make me feel like a fangirl. |
How-to guide
- How-to guide:
- A step-by-step user guide that completes a real-world task with your app. A how-to guide is limited to a single task and doesn't detail concepts, but they often link to an explanation guide.
- Reader’s goal:
- “I completed the task successfully.”
| Example | What works well? | What doesn’t work well? |
|---|---|---|
| Sending the user to another app | Android Developers |
Title and introduction; right away I know what this guide is about and why it’s important. Simple structure: headings, a brief paragraph, code, ordered tasks or diagrams. My focus remains on the content. |
Content in the video is different from the guide – this isn’t stated right away. This difference is only stated in the last sentence in the introduction.
I read the first two paragraphs then clicked on the video. The content in the video differed from the first two paragraphs – this left me confused. No prerequisite section such as Before you begin, Setup, Configuration. The Show an app chooser heading felt abstract because this task wasn’t mentioned in the intro. No links to related articles; like a Further reading section. |
| Creating an assistant | IBM |
The introduction has two simple sentences. 🤩 Right away, I know why I would want to follow this guide and where I could learn more. Directions use ordered steps. The guide includes other related tasks, each with ordered steps. |
No prerequisite section such as Before you begin, Setup, Configuration etc.
No links to related articles, like a Further reading section. |
| Writing a Custom Agent Check | Datadog | Succinct Overview.
Setup section with clear subsections such as Installation Configuration, Results, Verify. Further reading section. |
The content in some of the Note blocks felt long and buried.
The Sending data from a load balancer section felt abstract; I wish it was grouped under a “Use cases” heading. |
Explanation guide
- Explanation guide:
- A user guide that clarifies a single topic in your app. An explanation guide doesn't provide instructions, but they do link to how-tos and tutorials, or even a get started guide.
- Reader’s goal:
- “I have in-depth context of the app so I can get the most out of it.”
| Example | What works well? | What doesn’t work well? |
|---|---|---|
| Transaction states | Plaid Docs | Nice subtitle; to the point.
Descriptive headings that relate to me as a user. Example code and real-life example. |
Content is difficult to scan. I had to read every word in every sentence to grasp the topics in a section – I may have to set aside time to read this guide. |
| Theming | React Spectrum | Nice subtitle; to the point.
Descriptive headings that relate to me as a user. Content is really easy to scan; every header has a short paragraph. Example code further explains concepts. |
Very little! But I wish this guide led me to related articles. |
| Nodes | Kubernetes | Well structured with descriptive headings.
Everything I need to know about Nodes is on one page6. Which is nice because I can jump to the sections I need, and return to this page to learn more when I need to. |
The page does have a lot of content, but since I know this isn’t a how-to guide, I can digest the information when I need it. |
Reference guide
- Reference guide:
- A user guide with technical facts or specifications about a software element in your app.
- Reader’s goal:
- “I found the information I needed quickly; I’m back to working with the app.”
| Example | What works well? | What doesn’t work well? |
|---|---|---|
| Capture Session Reject Payload | Shopify | Love the Map with the “Mutation with this payload” diagram.
Mutation with this payload section; very rare in API docs. Descriptions are grammatically correct and in plain English. |
Very little! Though I do wish the objects didn’t use red or pink as colors. I thought of an “error” right away. 😕 |
| Get User's Saved Albums | Spotify | Request section with clear parameters, descriptions, and Example value, Default value, and Range – so helpful.
Response section with returned payload, attributes, and description of each attribute 🤩 – so rare. Descriptions are grammatically correct and in plain English. |
Very little! But it took me a minute to find the full request path: https://api.spotify.com/v1/me/albums. |
| Images | OpenAI API |
Request path available right away. Descriptions are grammatically correct and in plain English. White space. 🤩 |
No descriptions of returned payload7. |
| kubectl | Kubernetes | Love the easy-to-understand headings; Synopsis, Options, Variables.
Simple structure keeps my focus on the content. Descriptions are grammatically correct and readable. |
List under See also is long. When I clicked an item I was led to auto-generated docs. This confused me because I wasn’t sure which guide had correct info. |
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.
- Troubleshooting guide:
- A user guide with solutions to problems with your app.
- Reader’s goal:
- “I found a solution for my problem with the app, and solved it quickly.”
| Example | What works well? | What doesn’t work well? |
|---|---|---|
| Troubleshooting TechDocs | Backstage | Headers are specific to the errors or problems I may see. | No introduction after the title. Even a brief one would help me understand if I’m reading the right Troubleshooting guide for my needs.
Difficult to scan, I can’t spot the context that caused the error in the first place, and the solution. |
| Troubleshooting Applications | Kubernetes |
Clear, brief introduction. Links to relevant debugging guides; each debugging guide provides context (in the introduction) and detailed directions to debug the error. |
Nothing! |
| Common Chrome browser issues | Google |
Clear, succinct title. Issues are grouped by type, then use case. 🤩 Each issue provides a brief context then subsequent resolution. |
Very little! A short introduction after the title may be helpful. Something like “These issues are common to Chrome on any device”. |
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!
