As part of my computer science studies, I had many (at first glance) useless subjects, including one where we learned how to write documentation/reports in LaTeX. In retrospect, I see that mastering LaTeX helped me learn the ingredients of creating effective, readable and useful documentation.
In my current role as a Software Engineer, I can confidently say that the proper practices for writing documentation I learned back then have helped me. Here are some tips and advices on how to create high-quality technical documentation.
TL;DR - be precise and consistent, use a simple language and try to provide context and examples.
Provide context
An “Introduction” section can be very valuable in technical documentation. It can help the reader understand the purpose of the document, the scope of the document, and the intended audience. Here are a few reasons why you should include an extensive introduction:
- It provides context: An introduction can give readers an overview of the purpose and scope of the technical documentation. This helps them understand how the information in the document relates to their specific needs and how it can be used.
- It’s a great place to put important information: An introduction is a good place to put any information that is critical for readers to know before diving into the technical details of the document.
- It can help with onboarding: An introduction can also be a great tool for onboarding new users or team members. It can provide them with a quick overview of the project or system and give them a sense of what they will be working with.
Be consistent
Consistency is another important aspect of technical documentation. This means using a consistent style, formatting, and layout throughout the documentation. Consistency makes the documentation easy to read and understand, and it also makes it easy for users to find the information they need.
Using a consistent style means using the same tone, language, and vocabulary throughout the documentation. This helps to create a sense of cohesiveness and makes the documentation more readable. It also helps to avoid confusion and misunderstandings.
Be detail-oriented
When it comes to technical documentation, attention to detail is crucial. This means ensuring that all the information provided is accurate, up-to-date, and complete. For example, if a user is following a set of instructions to troubleshoot a problem, it’s important that all the steps are listed in the correct order and that all the necessary information is included. If a step is missing or the information is inaccurate, the user may have a difficult time resolving the issue.
Being detail oriented also means checking for and correcting errors such as typos, grammatical errors, and formatting inconsistencies. These types of errors can make the documentation difficult to read and understand, which can lead to confusion and frustration for the user.
Consistency and accuracy in technical/software documentation are crucial to providing easy-to-read, accurate, and complete information.
Label everything
Labeling pictures and tables is important because it helps readers understand the information presented in the document. Without proper labels, readers may struggle to understand the context of the information and how it relates to the rest of the document. Additionally, clear labels can make it easier for readers to find specific information, which can save them time and frustration.
Try to label all pictures and tables and give them appropriate labels that can be referred to in the text. Don’t use phrases like "table above" or "image above" in the documentation - it’s imprecise. Always refer to the labels, such as "image 1 shows the results" or "table 2 shows XYZ".
Example: Figure 1 shows the AI generated image of moon.
Figure 1: AI generated moon image
Table of contents
A TOC is typically a list of the main sections and sub-sections of the documentation, along with page numbers or links that allow users to jump directly to the relevant section. This can be especially helpful for long or complex documents, as it can make it much easier for users to find the specific information they need.
A TOC can also be useful for providing an overview of the documentation, which can help users to understand the overall structure and organization of the information. It can also be helpful for users to have a sense of where they are in the documentation and what other sections they might want to explore.
Examples
Bad example
Title: "Software User Manual"
Introduction:
Welcome to our software program! We know you'll love it.
Here's a manual on how to use it. Good luck!
1. Open the program by clicking on the icon on your desktop.
2. Click on the "File" menu and choose "Open."
3. Select the file you want to open and click "OK."
4. Start editing!
This example of bad technical documentation is lacking in detail and organization. There is no clear target audience and the language is informal and unprofessional.
The instructions are not written in a clear and concise manner and are not broken down into smaller, manageable steps. There are no examples or screenshots to help users understand how to use the software. There is no information about troubleshooting or resolving issues that may arise.
Good example
Title: "Software User Guide for Beginners"
Introduction:
Welcome to our software program! We've created this user guide specifically for beginners to
help you get started with the program. In this guide, you'll find detailed instructions,
examples, and screenshots to help you learn how to use the software.
1. Opening the Program:
* To open the program, click on the icon on your desktop
* Once the program is open, you will see the main interface
2. Opening a File:
* Click on the "File" menu
* Select "Open"
* In the "Open" dialog box, navigate to the location of the file you want to open
* Select the file and click "Open"
3. Editing a File:
* Once a file is open, you can start editing it
* To save your changes, click on the "File" menu and select "Save"
4. Troubleshooting:
* If you have any issues, please refer to the troubleshooting section of this guide or contact our support team for assistance.
This example of good technical documentation is clearly written for a specific target audience (beginners) and uses a professional and clear language.
The instructions are broken down into smaller, manageable steps and include examples and screenshots to help users understand how to use the software. It also includes a troubleshooting section to help users resolve any issues that may arise.
Good documentations I like and use
- Django - the documentation is very clear and concise, it’s easy to find what you need and it’s well organized. It also has a lot of examples and screenshots
- GitHub - easy to navigate, well organized, and has a lot of examples and screenshots
Using emojis
The use of emojis in technical documentation is a matter of personal preference and company style. Some people believe that emojis can make the documentation more friendly and approachable, while others believe that they are unnecessary and can detract from the professionalism of the documentation.
Using emojis in technical documentation can be appropriate if they are used sparingly and in a way that enhances the readability and understandability of the documentation. On the other hand, using too many emojis or using them in an unprofessional way can make the documentation appear less serious and make it harder to read.
However, personally I like using emojis in technical documentation. I think they can make the documentation more friendly and approachable, and they can also help to break up the text and make it easier to read. I also think they can be a fun way to add personality to the documentation.
Conclusion
Writing effective technical documentation requires a lot of effort and attention to detail. By following these tips, you can create documentation that is easy to understand and navigate, which will ultimately help your users and improve their experience with your product or service.