Before getting started, I want to provide a quick diversion that covers templates and how to apply and use them before you start documentation from scratch. Content templates typically consist of headings or sections that you can add to different content types, optionally with prompts and guidance on what to add under each heading. Over time, documentarians tend to create their own templates, adding them to content creation workflows for all to use. If you’re unsure where to start with templates, I recommend community resources such as the Good Docs project (https://thegooddocsproject.dev), which has worked hard to create many starter documentation templates for people to pick up and use. For each content type covered in this chapter, I include links to relevant templates from the project and/or my thoughts on a template you can start with.

So, let’s actually get started.

This content type helps people learn how to get started with a project or features.

Most inexperienced users start their journey with you via a Getting Started guide or onboarding experience. Getting Started, sometimes called a QuickStart, is typically a text-based guide that contains other media or interactive components.

Onboarding is sometimes called a tour or in-app help and is typically part of an app or product experience. It contains text that you might be involved in creating (I would say “should,” but that’s not always the case).

A detailed overview of Getting Started

I already covered some aspects of creating Getting Started guides in Chapter 1, but it’s a big topic, so the content you are likely to spend the most initial time on is worth covering in more detail. Whether you call it Getting Started, QuickStart, or onboarding, the first steps a user or potential user makes with a product are crucial.

If a Getting Started guide showcases what’s best about your product and gets new users started on their journey with you, then tutorials, sometimes called how-tos or guides, take them on the next steps.

As you might expect, the breadth and detail of tutorials or guides depends on your project, but here’s my general advice.

If your product or project has identifiable sections or sub-projects, they need tutorial sections. Do you support different ways to use your product – for example, a Command-Line Integration (CLI) tool, a visual interface, and an Application Programming Interface (API)? Perhaps you also support continuous integration (CI) or have applications and plugins in third-party marketplaces? If so, all of these need at least one tutorial on how to use them. If one of these sub-areas is particularly complex – for example, the visual interface has many different sections, or the Software development kit (SDK) consists of several components...

This section includes technical details of how individual components, functions, or APIs work.

I have always considered the differentiation between reference documentation and everything else in the following way:

• A reference document tells you that a hammer is for hitting things, wood is from dead trees that you can build things with, and nails are small, sharp, pointed bits of metal
• A guide or tutorial tells you how to build a shed with wood, hammer, and nails

Depending on the project and technology type, a reference section could include the following:

• SDK function details
• API endpoint details
• Architecture and design details
• Security and privacy details
• Whitepapers and academic papers

The terms API and SDK can sometimes be used interchangeably, depending on the project or product.

I start with SDK documentation, as you can typically build the reference documentation as you build your code.

Most SDK methods help...

A blog post is an end-to-end, self-contained piece of content, normally outside of documentation, that teaches the reader a practical technical lesson.

While not always a content type a documentarian is asked to write, you may be asked to help out, especially in smaller companies where you are one of the few people with the desire and skills to communicate clearly. Blog posts are often a good way to learn about a product or feature from start to finish. As blogs are usually promoted by marketing, outside of QuickStarts, they are also often the first way someone discovers a project, so they are worth doing well.

Much of the advice on structure and language presented in this book for documentation also applies to technical blog posts. There are a couple of main differences.

People generally read documentation when they need to, dipping in and out to find the information they need at the time, whereas most people read a blog post from start to finish, hopefully...

This chapter covered the different documentation types you need to create to fully document a project or product. These are as follows:

• Getting started, onboarding, or QuickStart: How people take the first steps with your project or product and some of the standout features
• Tutorials, guides, or how -tos: Further step-by-step instructions that cover particular use cases or features
• Reference: In-depth details about the function of individual components or the principles behind them

The next chapters cover how to write the content for these document types, starting with every writer’s favorite topic… grammar!