Guide to writing (good) documentation
It caught my ear that not everyone knows what it requires to write good documentation. Well, let me tell you. There are many principles on how to create sentences, paragraphs, or lists, how to write instructions or create screen captures. However, I do not want to talk about such details. In this article, I want to describe the main process. Here is a glimpse on a document writer’s job.
Always ask the right questions
At my job, I sometimes author documents to be published on our documentation page, other times I review documents of other colleagues or edit existing documentation. At the beginning, it is like a detective investigation. The writer must find, analyze, and sort all kinds of information from various sources (for example, a functional specification and marketing materials; interrogating developers or analysts) and include only relevant information. While gathering information, it is essential to ask the right questions (who, what, where, why …). My favorite question is “Why?”. Why should I include this information in the manual? Why do users need the information? Why is the information relevant?
Adjust to your audience
There are always users who will use the manuals and you should write with that in mind. Knowing what skills, knowledge and experience they have, will help you consider the level of details that you need to include. You should create a manual that is oriented on user tasks rather than functions.
I like to demonstrate a good documentation with a recipe example. Look at the picture below. It contains a descriptive title, prerequisites (ingredients) i.e. what you need to get started. There is a step-by-step guide (how to cook the meal) where each step starts with a verb, image that supports the text and additional important notes.
Now, let’s talk about the writing process.
- It is good to start with an outline, so that you can better imagine the future manual. If you are happy with the outline, you can start writing. Use the KISS (keep it simple & short) and STE (Simplified Technical English) principles. By following these principles, the documents will be more clear, understandable, and usable.
- When creating the first draft, do not bother with correct spelling or grammar. Concentrate on writing. You (and/or a reviewer) will correct the spelling mistakes, grammar, and formatting during the first review.
- During the first review, the writer goes through the information, corrects mistakes, and rewrites information. We can be sometimes blind to our own mistakes, so it is useful to involve a colleague in the review process. After the review and incorporating review comments, the writer prepares a second draft.
- After you have a second draft, you can proofread it. During proofreading, search for inconsistencies in text, identify necessary changes, check the manual for broken links and cross-references or add them where needed. An interesting proofreading technique is to start reading at the end of the document, or read the document out loud. It is also useful to check whether the content is logically arranged one last time.
- A reviewed manual needs some testing. In the testing phase, keep your deadline in mind. If you do not have enough time, pick some random tasks from the manual and try to complete them in the application. You may also think about some problem that users might experience and search for the solution. Are the search results relevant? Will users find the solution to their problem?
- After testing the documentation, you have a final draft. You check it again before sending it for approval.
- When the final draft is approved, you can publish it.
How about documenting in an agile environment? The main difference between agile and “regular” is that in agile process, the writer uses more bulleted or numbered lists, simplifies information and documents only stable features. It is good to document after each iteration, updates are done only if necessary.
And here is some useful reading: