Product Documentation: Types and Best Practices for Devs

The software engineering industry is highly competitive. Besides raw engineering skills, communication skills are becoming more and more essential for devs. For instance, more devs commit themselves to public speaking. 

However, it’s also important to effectively communicate new features to external users and provide them with tutorials or guides. Writing external documentation is especially important for Open Source products. Therefore, developers need to learn how to write practical technical tutorials for product users.

In this blog post, you’ll learn the following aspects of technical writing for developers:

• What’s the difference between a guide and a tutorial?
• How to structure a technical solution?
• What’s the importance of feedback loops and success moments?
• Why does a golden path for technical content matter?
• Why should you define your audience first when writing technical content?
• What tools can help you with technical writing?

What’s the difference between a guide and a tutorial?

You might wonder why you should know the difference between a guide and a tutorial — aren’t they the same? Understanding what types of technical content exist is crucial to effectively communicate code changes or new features to a technical product.

• How-to guide solves a particular problem and requires previous knowledge about a technical product. A guide answers a question a user can formulate after using the product. For that reason, how-to guides are goal-oriented.
• Tutorial tries to educate the user and shows a complete example from beginning to end. Therefore, the user doesn’t require any previous knowledge and the focus is learning-oriented.

To give an example, let’s assume an Open Source React framework. A tutorial educates the user on how to install the framework and create new web pages. The tutorial takes a step-based approach to make it easy for any user to follow along.

This React framework also offers guides that solve specific users’ questions. For instance, how can you create a web form using the framework? How can you share state between nested web pages?

For that reason, most developers prefer writing how-to guides because they are lightweight and quick to write. On the other hand, tutorials are key for the adoption of a technical product and need to be explained clearly, handholding the user with each step. The writer guides the user during the learning process. A poorly written guide results in a flawed learning process, causing the user to abandon the framework and pick another framework with better technical documentation.

How to structure a tutorial?

A tutorial always starts with an introduction that explains who the tutorial is for and what you will learn. It’s important to list this information to help the user determine if they should continue reading this tutorial.

Further, you can include a background section to provide additional information about the tutorial or link to other resources the user should read first. The background section is followed by a requirements section that lists technical requirements the user needs to meet in order to complete the tutorial. Ensure clear instructions and links to resources to help the user find the right tools they need.

Next, you can start the tutorial explaining the product or a feature using easy-to-understand, short steps. And lastly, add a conclusion to your tutorial to summarise what the user has learned. It’s also an excellent opportunity to link to a follow-up tutorial or reference docs to allow the user to experiment with the code using the tutorial as a base.

Note that this is the core layout for a tutorial. It’s possible to add more sections to a tutorial, but keep it simple. 

• Introduction (who, what, why)
• Background
• Requirements
• Steps
• Conclusion (what did you learn, further learning resources)

Tip: Add small labels to your tutorial that indicate the length (time) and complexity (beginner, intermediate, advanced). You can find a great example in the Binance Academy with additional filters.

What’s the importance of feedback loops and success moments?

Providing the user with continuous feedback allows them to learn faster because they can verify what they are doing is correct. For instance, add a screenshot of the expected output. You want to avoid a situation where a user spends 30min following your tutorial to discover they made a mistake at the beginning and now have to start again. I don’t have to tell you that this negatively impacts the learning experience.

In other words, you want to add multiple check-in moments to a tutorial to celebrate success. You give the user the feeling they are doing things right and encourage the learning process.

To increase the ‘aha’ moment, it’s important to provide sufficient context to users. Some users prefer to just follow the tutorial, while others check out each function in the code and read the reference documentation to get a deep understanding of the product.

Therefore, make sure to cater your tutorials to both users, linking to relevant code snippets in your codebase. For that reason, it’s also essential to have a clean codebase structure with good code commenting to assist experienced developers in their learning process. It all adds to a more positive learning process, creating stronger “product ambassadors.”

Tip: Use Stepsize issue tracker in the editor to make it easier for Engineers to add and see context to your code:

• Add code comments, bookmarks, TODOs
• Link codebase issues to code
• Add issues to your sprints with Jira and other PM tools integration

Why does a golden path matter for technical content?

Documentation specialists often say there should be a golden path through your documentation. It means there should be one unambiguous flow through your documentation developers can follow by completing tutorials and clicking on the following resource listed. In the end, the developer has learned about the most important aspects of your product. 

This golden path principle also applies to technical writing. Many beginning writers tend to include many references and "side quests" in their tutorial, making it hard to follow a tutorial because they end up completing another tutorial before completing the original tutorial. You want to avoid this situation absolutely.

If you want your users to complete another tutorial first, make sure to list this in the requirements section and make it clear who the audience is in the introduction section. 

Why should you define your audience first when writing technical content?

Who are you writing for? Does this user have previous experience with your product?

For beginner users, it's helpful to include explanations and "read more" links that are optional to learn more if they want to. Also, avoid abbreviations. 

For advanced users, tutorials can be more straightforward without much fluff. Often, these users will use reference documentation or quickly scan through a guide to see if it solves their problem. You should avoid writing a tutorial when the user is actually looking for a guide that solves a specific question they have. You don’t want to consume more of a user’s time than needed. If you want to get started with technical writing, look at the tech writing courses created by Google.

Make it easy to find relevant context in your codebase

Mess in the codebase makes it harder for Engineers to create technical documentation and find relevant contex for the key features. Clean up your code regularly and add more context to you code by describing the problems you see in the codebase.

You can use various various tools that’ll help you clean up your codebase but the quickest. The easiest way to get started with codebase issues is to use free Stepsize extensions for Visual Studio, VS Code or JetBrains that integrate with Jira, Linear, Asana and other project management tools.