Authoring technical documentation is a necessary part of preparations as you market your product. Yet before you start writing and designing your documents, you need to define the type of documents you make. It’s necessary to understand it in order for your docs to be read and perceived right.
Types of Documentation by Purpose
There are two basic types of documentation by its purpose, depending on who it is made for. As you might have guessed, these types are:
- User documentation (also known as user documents). It is meant for users who don’t have to be tech-savvy but require the answers to questions that may arise. It is usually made in the form of HELP files or portals. It skips all the unnecessary technical details and only has the most basic of them. There should be technical requirements for the software/service, instructions about installation, registration, and authentication (if necessary), and the description of features with screenshots and videos.
In addition, there should be a troubleshooting guide with an explanation of possible error messages. It also includes release notes that reflect changes in updates of the product. As for the language, it should be simple and not use too much technical terminology. Slang should be avoided completely.
- Technical documentation (also known as process documents). It is created for developers and maintainers that start working with the software when it’s already developed. So it needs details on required hardware and software, data structure, expected inputs, validation checks, and how the data is processed, with diagrams and flowcharts to make it visual.
This documentation should be exhaustive, though there still may be a need for, say, comments in the code. In this type of documentation, one can use professional vocabulary and even slang, as its audience is supposed to know it well.
Documents concerning the management and marketing of the software are formally a separate category. For example, market requirement documents that view the software from the customer’s point of view and explain the target audience. There are other similar documents that are made for internal use but not focused on technical aspects.
Different as these types of documentation are, they still require similar approaches to make. Each of them falls into one of the categories of documents by structure.
Types of Documentation by Structure
With their contents quite different, documents are always organized into one or another sort of structure. These structures are defined by what users expect to find in them, depending on their awareness and experience.
- Tutorials. These types of documents address an inexperienced user and explain processes step by step. Usually, tutorials cover the entire functionality of the product.
- How-to Guides. These are, effectively, types of tutorials, but they are smaller and focused on solving particular problems. They may cover all the aspects of using the software or only the most sophisticated ones. By the way, “how-to” is arguably the most frequent word in search requests regarding your software.
- Explanations. These also address inexperienced readers, but, instead of practical application, focus on theory and general how-it-works stuff.
- References. These documents are designed for experienced users that require specific information. They contain either this information directly or links that lead to more detailed explanations of the subject.
Regardless of the type by purpose, most documents fall into one of these categories. There can be documents that combine elements of two types. The complete documentation may contain documents of all these types plus combined ones.
Tools for Tools
As you plan your documentation portal, you can include these types of documents in various sections of it, regarding topics and target audience. To create technical documentation in all its variety, you will need flexible tools that allow for making each type of them separately and yet combine them in themed portals with a common style. A good platform for creating online documentation offers possibilities (including templates) for all these types of documents.