This opinionated guide will teach you how to quickly write a piece of useful documentation. If you are a developer who has never written documentation before, this is a good place to start.
If your company already has documentation, ask your colleagues how they write and publish it. Use the same process they do, so that you can seek their help if you need it. You can skip this section if this is the case, and only use the rest of this guide for inspiration. Follow your colleagues’ instructions instead.
If your company has no established documentation process, you will need to make a few decisions yourself. Generally, your options are as follows:
- Writing a docx document using Microsoft Word or similar software.
- Writing a wiki page.
- Writing a Markdown document using any modern text editor.
- Writing a reStructuredText document, and using Sphinx for publishing.
Use docx or similar if your company produces a lot of internal documentation in this format and everyone is familiar with where it is stored. This is rarely the case in modern agile teams.
Use a wiki if your organization wants to allow people with different knowledge and experience to contribute to the documentation.
Use Markdown if you expect this to be a small piece of documentation and you want to place it in a version control system.
Use reStructuredText if you are setting a policy for version-controlled documentation in a bigger project. Sphinx provides many reasonable defaults that will help you organize your content from the start.
The rest of this guide assumes that you want to quickly write a single document in Markdown, place it in a git repository, and publish it as a PDF file.
Every modern text editor supports Markdown, so you can use your current tools to start writing documentation. Be sure to install extensions for Markdown syntax highlighting and spell-checking. If you do not use a text editor, or your text editor does not support Markdown, follow the steps below to set up Visual Studio Code:
- Go to https://code.visualstudio.com/ and download the installer for your platform.
- Install and launch Visual Studio Code.
- Click the Extensions button on the left and install two extensions: Spell Right by Bartosz Antosik, and Markdown PDF by yzane.
Your editor is now ready.
Create a new file. You can now start writing your documentation in Markdown. If you do not know the syntax, go to https://commonmark.org/help/ and read through the short tutorials. They cover everything you need to know to write documentation as code in standardized Markdown.
This section contains recommendations, tips, and tricks that will help your content read like professional documentation. Note that every writer develops a unique writing style and process as they gain practical experience. The more you write, the better your documentation will be. However, there are certain steps you can take to make your content better, even if you have never written documentation before.
Start by thinking about your audience. Try to identify who will read your documentation and what their goal will be. What do they expect to see? What information are they looking for? What do they already know about this subject, and what details will you have to provide yourself?
Next, think about the structure. Do you need to explain something before you can explain something else? What should you start with?
Finally, think about what types of resources you can use in the documentation. Do you need any screenshots? Do you need links to websites or documents? Collect such resources and include them in your documentation as necessary.
Once you have a basic idea of what content you need to write and how you need to structure it, start writing.
Allow yourself to write down all the ideas you have about the subject of your documentation. Try not to censor yourself. Do not edit, change, or correct your initial draft. Just write - there will be plenty of time to edit later.
When your first draft is ready, you can start editing it. Try to incorporate the style suggestions from the next section at this point. Expect to edit a lot at the beginning. First drafts are meant to be rewritten and corrected, so do not judge yourself if your document needs a lot of work. The best way to quickly check your content for common errors is to copy a section to the Hemingway Editor. This useful tool will analyze your text and suggest improvements. While far from perfect, they usually help make the text more readable.
- Write short, clear sentences. If a sentence needs more than two commas, you can probably simplify it. Complex sentences make your instructions and explanations more difficult to follow.
- Only include what is necessary. Make sure all sentences and paragraphs provide new information. If they don’t, edit them out.
- Address the reader directly. This mimics a conversational style that is easier to process.
- Use active voice. Active voice encourages you to clearly specify who performs an action. This makes your documentation easier to understand. Passive voice is still acceptable, but you should not use it too much.
- Use singular they when talking about people (users, readers) when their gender is irrelevant to the subject of your document.
- Avoid colloquialisms, jargon, humor, and stereotypes. They might make your documentation obscure or offensive.
If you have any doubts about style or grammar, or want to learn more about writing high quality content, use the resources below.
For American English:
For British English:
After making initial adjustments to your document, you can now start a review process. If time permits, you should first review your content yourself, and then share it with someone else.
Before you start, try to take a break. A few hours, or even a day, can help you clear your head from any assumptions you made while writing. This will allow you to notice information that is missing from your document.
When you are ready to begin, open your file in Visual Studio Code and press Ctrl + Shift + V. The editor will display a preview of your documentation. Use it to check your content. Seeing the document in a different way like this can help you spot problems that you would otherwise miss.
Read through the entire document to see if the content flow is correct. Is everything explained in the proper order? Is the content easy to follow, or are there any leaps between subjects?
Check if section names are clear and make sense. Clear section names make the document easier to scan for valuable information.
Check the syntax. Do heading levels make sense? Are all links working correctly? Are lists displayed as intended?
After you have corrected all the problems and errors you were able to spot yourself, it is time to ask someone for peer review.
In Visual Studio Code, press Ctrl + Shift + P to display the Command Palette. Type Markdown PDF in the palette box and press Enter to generate a PDF file.
Share the PDF file with a colleague and ask them for a review. Even if that colleague is not a writer, their unique perspective will allow them to spot problems you have missed. Be open to their critique. Peer review is the best way to learn and improve your writing.
When the peer review is finished and you have corrected all the errors and problems in your document, you can publish it. Congratulations!