Technical documentation for software: Online-Help
To perfectly support users working with software, online help should cover specific work situations and should provide the required information for current tasks with minimum search effort. The online help features some specific attributes which make them very well suited for software documentation. Display texts on electronic devices and user interface texts are also parts of the software documentation.
Unique characteristics of online help
The online help covers specific task contexts to give users optimum support when they are applying the software. The required information is provided via the online help in a task-oriented manner without the need to perform extensive searches. The software documentation is structured according to the tasks users have to complete. Users can access the online help via Help buttons or by using the F1 key.
- Context sensitivity
The context sensitive online help specifically provides information for the current situation of the user. Usually, this means describing particular elements of the software, such as buttons and dialogs. The information exactly fits the user’s needs and is very specific and detailed. - Modularization
The online help is created with a topic-oriented approach: Content is separated into modules which deal with a self-contained subject matter. To get to other relevant subject matters, users can follow links to the respective topics. That way, users can find perfectly fitting information. - Hypertextuality
The online help is a hypertext structure which consists of topics linked in a kind of net. This distinguishes the online help from linear documents following the typical book structure. Users can call on navigational tools to access information in a self-determined order. - Screenshots in Online-Help
Screenshots in Online-Help - Navigation
Apart from links, there are additional elements supporting the navigation in an online help:
Dialog history: Users can open a chronicle of pages they have opened.
Breadcrumbs: Users can see their current position in the online help.
Backtracking: Users can backtrack the topics they have accessed step-by-step.
Bookmarks: Users can create bookmarks in important topics to make them easier to retrace. - Comments and Feedback functions
User interface text
Display texts on electronic devices and user interface texts are integral parts of the software documentation and must be easy to understand, consistent and correct, to ensure safe operation by the user. Developers often write these types of texts. Technical writers then sometimes review and edit these. There are rules to be observed during this process.
Users tend to read user interface texts differently than continuous texts, such as seen in the online help. They do not read from the top left to the bottom right, but rather they glance over the entire user interface and then skim the texts and the buttons. They do not read, they skim. There is another difference when compared to normal, continuous text: users tend to stop reading immediately once they have found what they are looking for.
There is often very little space to accommodate the texts. For this reason, these texts have to be rather brief, concise and consistent. Consistent labelling of buttons and other elements of the user interface are essential to ensure usability.
Message texts, confirmation dialogues and instructions shown on the user interface are in good hands with technical writers. They check whether texts are consistent and easy to understand. Fault messages should be particularly informative. They are not only used to describe the fault but also explain how the user can resolve or correct it. The same applies to user interface texts and the entire corporate content alike: the applied terminology must be consistent.
Checklist to help compile user interface texts
- Pay attention to terminology. Do not use internal expressions.
- Use as few words as possible.
- In the case of complete sentences: No passive voice.
- In the case of handling instructions, the typical structure of this type of text has to be applied.
- Texts translated into target languages may be longer. Plan for extra space to accommodate translations.
- Stipulate rules for dealing with upper and lower case characters and punctuation. It is a good idea to include these rules in editorial guideline.
- Phrasing informative fault messages. What is the fault? How is it eliminated?
We provide the documentation for your software. Do you have any questions? We can help. As a supplier and reliable service provider, people text will work with the authoring system of your choice, to provide the documentation for your software. The creation process for your software documentation will be seamlessly integrated into your editorial processes.