Advent of Technical Writing: Types of Documentation

This is the fourth post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

"Technical writing" is a broad umbrella. It can mean everything from scientific communication to writing instruction manuals. I wanted to take some time to document some of the types of documentation I have encountered in my work at technology startups. I will discuss the key features of each type of documentation, allowing differentiation.

It is rarely the case that your software documentation is in a single place. It is important to know different types of documentation so that you know what to write and where it should go. Furthermore, how you write content -- a blog post, a product documentation page, open source documentation -- will differ depending on where the documentation is going to be published.

Let's talk through a few types of documentation you may encounter in software companies. We will talk about:

• Product documentation
• Blog posts
• Open source documentation

Product Documentation

Product documentation collates all the information someone needs to use a product. Depending on your product, this documentation is include more images than other types.

The primary goal of product documentation is to educate the reader on how to use your product. Through each page, a reader should be able to accomplish a specific task. For example, Roboflow makes computer vision technology. Our documentation covers everything from creating a Project (a feature in our product) to deploying vision models with our technology.

Product documentation not only shows someone how to do something, but it may also introduce someone to new features in your platform. For example, someone may come to the Roboflow documentation to learn more about how to annotate an image. They may then explore the Annotate section of our documentation to find new features.

You should document as much of the common actions that users can take on your platform as possible, with visual aids to assist readers in their understanding.

Here are a few examples of product documentation:

• Supabase
• Elasticsearch
• Roboflow

Blog Posts

"Blog posts", like "technical writing", is a broad term. A blog post can be:

• A post that announces a new product and shows how to use it. This should not replace writing a page in your product documentation. Your product documentation should be the comprehensive, authoritative source on all products and how to use them).
• A tutorial on how to use a product for a particular use case. The "for a particular use case" is important here. Whereas product documentation should be as general as possible, you can use blog posts to show how a particular segment of users can use your product. For example, Roboflow has blog posts on how to use our video inference API to build a search engine. We document how to use the video inference API in our product documentation. The video search blog post explores a particular use case in more depth.
• A general education post. For example, Roboflow has posts that define terms like object detection, zero-shot classification, keypoint detection, and more. These posts are intended to help people learn about a concept, with reference to our product where relevant. The foundation knowledge built in such a post can then be used to accomplish a task, such as may be documented in a tutorial.

There are many other types of blog post that are not related to technical writing. Thus, I will not talk about them here.

Blog posts are an effective way to build knowledge on best practices and to create a repository of general information about jargon and topics that users of your product may encounter.

For example, you can use the Roboflow blog to learn about how to use the Segment Anything model. We have Segment Anything support for automated labelling in our product, which is documented in our product documentation. We also have a blog post that shows how to experiment with the model yourself, which is catered to an audience with more machine learning experience.

Examples of blog posts include:

• How to Deploy Computer Vision Models Offline
• Launch: Roboflow Video Inference API
• What is Zero-Shot Classification?

Open Source Documentation

Open source documentation is like product documentation in that your goal should be to give someone all the information they need to use your product. With that said, writing open source documentation differs from writing product documentation in many ways.

Open source documentation involves several aspects, including writing:

1. A README, which shows someone how to install and use your software;
2. Contributing guidelines and a code of conduct;
3. Guides which show how to use key parts of your software;
4. Code documentation.

A small project may only have a README, and ideally contributing guidelines and a code of conduct. Larger projects with more features tend to have dedicated documentation sites which explain each feature in depth. One such example is Autodistill, an open source Python package that you can use to auto-label images.

Autodistill has documentation which covers:

1. Getting started with auto-labeling data using Autodistill.
2. How to use key library features like plot() to plot an image with labels, compare() to compare two or more models for auto-labelling, among others.
3. Information about the Autodistill ecosystem of packages, including what packages are available and how to use them.

Some of this documentation, such as the getting. started guide, is written on a documentation website by hand. Some documentation is auto-generated from the code docstrings. We use mkdocs to generate and render documentation.

The amount of documentation you need will vary. At a minimum, you should have all the documentation someone needs to use your software with minimal friction. Generally, the more documentation you have (that you are willing and able to maintain!), the better.

Examples of open source documentation:

• supervision
• Hugging Face Transformers
• llamafile

More Documentation

There are many more forms of documentation you will encounter, but I have had less or no experience writing them so the extent to which I can lend insights is minimal. With that said, I can share some high-level information. Here are a few other forms of documentation that exist in software:

1. Standards: These are well-researched documents that take extensive periods of time to make. Standards typically go through a robust technical review process (i.e. the W3C Candidate Recommendation process for the W3C) to ensure the technical details of the standard.
2. Manuals: Manuals document how to use a product in full. You could think of online product documentation as a manual, except spread over many pages.
3. Help Center Documentation: This may be used in addition to product documentation to answer specific questions such as how to delete an account. Help centers often provide both documentation and a form through which users can request support. Help center documentation can become duplicative, however. Be sure that your help center does not aim to document the key features in your product that are in your main product documentation.

Conclusion

The type of documentation you write as a technical writer or engineer will depend on your role. For example, I write product documentation, blog posts that showcase product features for specific use cases, and open source documentation. That is because my role spans across both growth, marketing, and open source. At a large company, you may focus solely on product or code documentation, depending on your role.

Join me tomorrow for my next technical writing tip!