Tutorial

Creating great documentation

2 years ago
15 June 2021
0 replies
535 views

Userlevel 6

Per
Super User
156 replies

The challenge – and why documentation is important

Making documentation is a way to communicate, instruct and record system information for any reference or operational purpose. Using documentation, it is easy to track the flow of progress in a system, and the workings of the system can very easily be explained. Documentation can be used to facilitate effective communication regarding the system between technical and non-technical users, and is very useful in training new users. It also helps to solve problems like trouble shooting.

The process

Making good documentation requires an investment in time and resources. To make sure you get the most of your investment, use a structured process. Organize your documentation process around five steps:

Plan
Write
Revise
Edit
Publish

Let’s look at each step in detail:

1. Plan

Your documentation process starts with a planning phase. You should use the planning phase to collect information, plan the structure of your documentation, and select where to begin. Documenting large software applications such as ERP platforms can be overwhelming in sheer size, and dividing your application into smaller areas which can be conquered at a time, makes the task easier to overcome.

Audience

The audience in your project are the end-users of your documentation. The users who will open, read and use your documentation. Understanding your target audience is critical to the success of your documentation project. During the planning phase, the project team will collect information about the audience. Ask yourselves questions like:

Who are they? (technical, non-technical, employees, non-employees, etc.)
What do they need to know? (what is critical, what is nice to know, prerequisites, etc.)
What do they already know?
Where or how will they be searching for the information?

The answers to these questions are important as they will guide your decision making later in the process. Make sure you understand your audience well. Don’t assume you know, but spend time asking people in the target audience group questions, that will expand your knowledge about them

Don’t

We tend to write in a way, that makes reading our texts require prior knowledge. And many times, what we want to tell our audience, is mainly about ourselves. Don’t assume your audience knows what you know. And don’t assume your audience want to know what you want to tell them.

Do

Make sure your documentation starts from the beginning. Include the precise prerequisite knowledge needed. Listen and learn what it is, your audience wants to know. Make your documentation close to the audience, and relevant. Make it about them, not you.

2. Write

In writing, something is better than nothing. Accept that things won’t be right the first time, and your initial draft most certainly won’t be perfect. But focus on getting started. Being perfectionistic will trap you in an infinite loop of write-delete-write-delete activities. You don’t do anything wrong, because you don’t do anything. Prior to writing your first lines of documentation, it may be helpful to collect and draw out your notes, thoughts and ideas into a storyboard, which can use as a guide through the necessary steps in the application.

3. Revise

In this part of the process, you will refine your documentation. Apply the knowledge about you audience here to think like your readers. Try to create a logical flow, for example using a question and answer format, or similar. Be concise and to the point. Don’t waste your audience’s time. Evaluate every word and phrase and be ruthless in reducing your text to the minimum necessary for reading comprehension. Use headings and bullets to allow your audience to easily scan the documentation.

4. Edit

Show your documentation to colleagues and stakeholders, and have someone proofread it before you publish it. Weed out any typos, bad spelling, bad grammar, and translation errors. If you are translating your documentation into multiple languages, use a proofreader with the translated language as their first language AND knowledge into the subject of the documentation. Test your documentation on a select sample audience. Let them use your documentation and ask them to speak out loud their immediate response, while you watch and listen carefully. Adapt your documentation according to feedback and retest if necessary.

5. Publish

Before you publish your documentation, bring back some of the considerations from the planning phase. Who are your users – where will they look for the information – do they want printed documentation, or web or perhaps mobile web? Which platforms do they already access and use for documentation? You may find a better strategy is to publish your documentation in several types of formats (print, online, etc.) onto several platforms, to reach as many in your audience as possible. Consider ways to allow and handle versioning of your documentation. You will be updating your documentation eventually, and understanding how to handle versioning of every content type and platform in use, will save you valuable time we needed.

Documentation lifecycle / Long-term maintenance

At some point in time after publishing, your documentation will need updating due to events such as versioning of your application, changes in processes, new languages added, etc. This means you should consider: Who will perform long-term maintenance? (roles, responsibilities, etc.) Organizational documentation conventions and styles If you have a large library of documentation, consider scheduled inventory and audits Good documentation is up-to-date according to latest updates and changes in the system and processes it documents, and continues to fulfill the exact requirements of the audience. As systems and processes change, adapt your documentation accordingly.

Templates for visual/written conventions and styles

Organizations who make documentation, should consider deciding on and implementing documentation conventions. Conventions should cover visual and written elements such as: How to use screenshots (size, location, highlight color, borders, etc.) How to write text documents (fonts, colors, styles, etc.) Other elements (logos, headers, footers, ToC, etc.) Often an organization’s marketing or communication departments have knowledge and opinions on these subjects and can quickly provide relevant resources and make final decisions. Once a common overall convention established, create templates (for example template word documents, etc.) for use in documentation projects. Adapt existing documentation to your template. The benefits of using templates are many. Using the same conventions will improve the quality of your documentation. As every documentation product is setup in the same way, your audience will know what to expect. Your audience will easier know how to use the documentation, as they get familiar with it. Documentation authors will also save time, as they are no longer required to make decisions on styles, etc.