Tech documentation best practices: Making devs love your docs

Technical documentation can often be difficult to navigate—but why is that? In this blog post, I'll walk you through best practices for creating clear, effective software documentation and writing excellent developer tutorials.

Remember, your technical documentation is just as much a part of your product as the software itself. Delivering a top-notch product with mediocre documentation doesn’t make sense. It can be the difference between developers adopting your platform or abandoning it out of frustration. My goal is to help you craft documentation that enhances your product.

What does good technical documentation include?

Good software documentation should include at a minimum the following items:

1. Overview or landing page

The overview or landing page for your documentation should act like a trailhead at the start of a hike. The trailhead guides different developers toward the paths that best match their goals and needs. 

Imagine arriving at a hiking waypoint where you can choose different trails based on your destination—some lead to scenic overlooks, others to waterfalls, and some to more challenging peaks. Similarly, your product offers multiple features, and the overview page should clearly map out these options, offering distinct learning paths that allow developers to head straight to the knowledge they need.

By doing this, you avoid a common pitfall: forcing every developer to hike through all your features before they can reach their destination. Instead, you let them jump directly to the feature they care about. It saves developers time and you increase the likelihood of them converting.

2. Quickstart

A quickstart is your most basic tutorial that gets developers up and running. It typically covers essential details like requirements, environment variables, and installation instructions. 

Try to leverage your quickstart to reach meaningful value. Avoid printing a “hello world” message to your terminal as it doesn’t demonstrate any real value or showcase the potential of your tool or feature. Developers want to quickly grasp your product, therefore, show them some real value.

3. Key concepts

The key concepts section lets you explain product-specific terminology that developers might not be familiar with. While you might assume developers will figure things out, it’s best to have such a section readily available because certain terms may not be as obvious as you think.

Here’s an example from a project called mintBlue, which uses the concept of “projects.” While projects are a familiar concept, mintBlue implements it in a slightly different way. In this case, a project acts as a container for transactions, and the same transaction can be added to multiple projects. What may initially seem obvious becomes less clear when you consider this unique implementation. That’s why they chose to include it in their "Key concepts" section.

For clarity, they also added a screenshot of the UI to build familiarity with the concept while reading the explanation.

(Source: mintBlue key concepts)

4. What’s new 

A “what’s new” section helps you to communicate product changes to developers besides the regular channels like email and socials. 

I find it a great section to have in your docs because it shows you are actively maintaining your product. Make sure to communicate changes using practical code examples instead of sharing release notes—nobody wants to read release notes.

5. Example apps

Including example applications is a major advantage. Developers can download them and test them on their own machines. It gives them immediate feedback on how your product works and how your features can be implemented. For instance, you can provide example implementations for popular frontend frameworks like React and Angular. 

To take it a step further, consider adding challenges to your example applications that require developers to modify the source code. This encourages them to actively learn about the different aspects of your feature. In other words, you are challenging them to learn quickly. That’s a win-win!

Next, let’s discuss what makes up a good tutorial.

What makes a good tutorial in technical documentation?

We have just discussed the essential elements for your technical software documentation. Now, let’s look at what makes a tutorial truly effective.

1. Overview

The overview section helps you to set the context. Sometimes, it’s not clear what the user will learn or what the purpose is of a tutorial. An overview section allows you to communicate this information up front. A developer can then decide based on this information if this tutorial is relevant for them.

2. Prerequisites

Few things are more frustrating than following a tutorial only to realize you're missing a dependency or other required components that weren’t mentioned. This wastes time and often forces you to restart the tutorial after installing the missing dependencies. Sound familiar?

You can avoid this issue by adding a prerequisites section. This ensures readers have a clear understanding of what they need before reading your tutorial.

(Source: mintBlue SDK documentation)

3. Summary or “What did you learn?”

The summary section reinforces the key information developers have learned throughout a tutorial. Similar to memorizing information, use this opportunity to highlight the key takeaways.

4. What’s next

Many improvements to developer experience in documentation are about saving time and guiding developers in the right direction. This is why you should add a “what’s next” section, as it nudges the developer to continue learning.

Often, after completing a tutorial, developers might be unsure about the next step in the learning journey. The “what’s next” section solves this problem by guiding the developer toward the appropriate learning path.

Now that we've covered how to structure effective tutorials, let's take a step back and explore the importance of information architecture. Organizing your documentation in a way that’s easy to navigate is key to creating a great developer experience.

Information architecture: Why it’s important

A good information architecture is like a trail map, guiding you through the mountains to your destination. The structure itself should give developers a clear sense of where to find the information they need, just by looking at how it’s organized. In other words, good information architecture helps developers find the information they need.

Take, for example, the information architecture of Cello’s documentation. It offers a clear progression, starting with the introduction to Cello, moving into quickstarts, guiding users how to use their SDK, and finally, offering a more in-depth reference guide for advanced users.

Another example comes from mintBlue’s docs, which are feature-oriented. Each feature has its own quickstart, key concepts section, tutorial, and how-to guides to solve specific problems related to that feature. This approach creates a cohesive "mini-documentation" for each feature, allowing developers to find all the relevant information in one place.

An interesting quirk in the mintBlue docs is that the “Transactions” feature starts with the onboarding and then provides the feature context. Sometimes, it’s more effective to give developers a quick, hands-on experience before introducing the technical, conceptual information. This approach allows developers to get a feel for how the feature works in practice, making it easier to understand its technical concepts.

Technical documentation examples

Here’s a list of my most favourite documentation examples.

Vault

I like the Vault docs as they have a great documentation landing page that clearly maps all the features and starting points to learn about these features. 

Cello.so

The Cello.so docs offer an elegant progression path in their documentation. I also love their implementation of the “what’s new” section.

Stripe

Stripe is a leader in the technical docs space, offering the best-in-class interactive documentation.

mintBlue

Many of the examples in this blog post come from the mintBlue documentation. Full disclosure: I’m the author of this documentation and implemented it based on my understanding of best practices and frameworks for good technical documentation.

Where should I store my coding documentation? Is GitHub a good place?

While GitHub is a good place to store documentation about your project, it doesn’t offer a great developer experience. For simple projects, this might satisfy, but as your project grows bigger and hosts more features, it’s recommended to spin up a dedicated software documentation website.

Don’t be afraid to continue using the README.md file in your GitHub repository to guide developers to your hosted documentation and provide some quickstart information to get them up and running.

Why is it good for developers to be good at documentation?

While developers excel at writing code, it's equally important to be able to clearly communicate how that code works. If you can’t communicate how your code works, few developers will understand the value of your product, regardless of how well it works.

A common pitfall is simply dumping information in a README.md file and expecting developers to understand the information you’ve provided. It doesn’t work this way. Effective documentation is about more than just providing information, it’s about guiding developers and providing an enjoyable learning experience.

In short, clear documentation can bridge the gap between code and understanding, ensuring developers can quickly learn your product and implement your solution.