You know about software documentation and its numerous applications? And you have an overview of helpful tools for creating step-by-step instructions?
Then you can almost start with the documentation! But before that, you should be aware of a few important steps and tips and tricks.
These will help you in the planning and creation of documentation and maximize its benefits.
What characterizes a good software documentation?
Very straightforward: It does not convey what you want to say, but what the user wants to know.
The user is always at the centre and user-friendliness is the top priority. The aim of all documentation is to close the gap between the user’s previous knowledge and the way he or she deals with problems, and in this way to successfully guide the user towards a solution. In the creation process, you should go through several steps:
5 steps to successful documentation:
- Target group
- Selection of the form
- Selection of the format
- Selection of the software
At the beginning you have to be very clear about what exactly is the problem and how it should be solved. To what extent and why do difficulties exist? What are the particular challenges? Where are the recurrent obstacles? Are there different variations of the problem?
A reproduction of the problem can be helpful to develop a better understanding of it.
Use existing data as a source for your analysis: check your e-mails and messages and answer particularly frequent questions by a documentation once for all.
2. Target group:
Then you also analyze the target user group that will utilize the documentation in the end. Are there any restrictions for the users? What knowledge already exists, what needs to be explained in particular detail? Also keep in mind that the documentation may be passed on to other users who may have less prior knowledge than the original users.
3. Selection of the form:
You must then decide what form your documentation should take: A reference manual, a user manual or a combination of both?
A reference manual explains the various functions of a software in a basic way and explains the different buttons, items, and dialog boxes the user will encounter. This is often done in the form of context-sensitive help, which means that the user is shown explanations directly at the respective button on the desktop.
A user manual, on the other hand, is dedicated to a specific problem and its solution. It explains how to perform a task with the software step-by-step from start to end and thus accompanies the user during the execution of a specific workflow.
4. Selection of the format:
Finally you have to decide which format the finished manual should take at the end: Word, Powerpoint or Pdf format? Or do you need the image files of the screenshots or an HTML format for your homepage? Do you need to be able to upload the documentation on a website? Or send it to potential customers or colleagues? You also have to decide which design you need for your documentation, for example if you want to display your company colors or the company logo.
5. Selection of the software:
Based on steps 1-4, you select the appropriate documentation software that meets your needs and requirements. For example, a software that can export HTML-files and that can be adapted to you corporate identity or a tool that performs all steps automatically – or whatever you wish. Here you find some advice for that.
Tips & Tricks – What do you need to consider?
- Specific and precise:
Include all potentially important information in the descriptions and highlight important data, such as technical information. Precise instructions create trust: users do not want to have to interpret, but want to follow clear guidelines.
- Do not expect knowledge:
Start with the simple steps and explain basic functions. If necessary, users can still skip steps – missing explanations cannot be compensated.
- User friendliness:
Use exactly THOSE tools and software versions that your users use. This way, they will identify themselves in your instructions and can transfer the steps one to one to their own computer.
Don’t overwhelm your users, but always explain only one solution at a time. For a new problem, it is better to create a new documentation.
Guide your users safely through the documentation with a logical and clear structure. Help them to understand the documentation with graphics and screenshots, as well as numbering. Cross-references can also be helpful.
Use texts that are easy to read and avoid technical terms. Address your users directly, in general with “you”.
Keep your documentation consistent and with a clear design. The use of your company colors and logo can be useful for identification.
Especially concerning important documents a test run can be helpful. Give your documentation to an uninvolved person and test the comprehensibility of the instructions. The feedback can help to uncover ambiguities and compensate for weaknesses by making corrections.
As always: Make the documentation as long as necessary, but as short as possible. Only directly problem-oriented instructions with the fastest possible solution will be used in the end.
With these steps and tips, there are no more obstacles to your successful software documentation. You can pass on information in a 1) simple, 2) fast and 3) precise way and enable others to use software successfully.
Good luck with it! If you have any further questions, we would be happy to hear from you at firstname.lastname@example.org – #shareyourflow