Ben Hall from Katacoda and Ocelot Uproar gave an awesome talk at OSCON 2017 about another topic near and dear to my heart: documentation! This is a summary of his presentation.

The journey to documentation begins before you think it does, on the very first page of your site. Users look at your website or GitHub—and often the examples and demos you post there—before they read any of your guides.

A big mistake we make in software is that we often give people the product to download and then give them access to the entire manual without any steps in between. Instead, we should approach documentation in incremental steps to build the user’s confidence.

Everyone is super busy and stressed, but when they come to your project site they’re motivated to solve a problem or improve something, and you don’t want to add additional stress and demotivate them with your documentation (or lack thereof).

This is why almost every entry-level computer science class teaches a “Hello World” example. It has a low barrier to entry and is easy for folks to learn. We want our documentation to get folks to a level where they are confident in acquiring more knowledge.

Think of documentation in the following steps:

1. Exploration
2. Getting started
3. Onboarding
4. Guidance and discovery
5. Reference

Step 1: Exploration

Imagine that someone has just landed on your GitHub page and they’re interested in learning more. What do you have there to hook them in and make them feel comfortable? Your GitHub page is the first step of your documentation, and you want to quickly and easily answer users’ questions about “why should I care?” so that you can pull them further in.

Ben shared these examples of sites that do this well:

• Kubernetes‘ site is very clear right away.
• Project Calico takes one line to explain its purpose, right at the top of the page.
• Kotlin is an example of how to get folks feeling confident about the product before downloading it.

Step 2: Getting started

Now that you’ve gotten your potential customers to care about your project, next you need to show them that your product is just what they need to solve their problem. You have about nine minutes before you lose a motivated user’s interest.

A great example of hooking the user is Stripe. It has a very clear “getting started,” complete with code snippets. It also includes small, discreet sections that are easy to digest and follow.

Step 3: Onboarding

The user now wants to use your product. You want to get them up and running easily.

A good example of this is Mixpanel. It has the documentation embedded right in the portal and doesn’t have lengthy text that you have to read. It makes the process engaging for users.

You want to get people over the first hurdle of seeing the system in action, so jump right into the process.

Stage 4: Guidance and discovery

Now that you have your users set up and running, they’re probably interested in what other problems your product can solve for them. They already have the difficult parts done—they got started, the system is running, and now they want to know what else is possible.

Twilio‘s website is a great example of this. You can easily pick what documentation is best for you from its handy header. It provides screenshots, videos, text content, and where to go next.

This stage is a good place to start promoting your community. Include options to explore your community and show what people are doing with your product.

Stage 5: Reference

Now your users want to be experts, so they will look for your in-depth documentation.

Given these steps, who creates documentation best?

Lego! Lego has the best documentation of all. Think about it, they don’t need to explain anything using words in their documentation; it’s all pictures. They not only help you follow the rules, but they also encourage you to be creative. They have a Lego ideas website where they let people publish their own creations. This makes the community feel more passionate.

If you’re a software maker, what do you think are the best ways to engage users with documentation? And, if you’re a user, what kinds of documentation do you think are most useful or helpful?