The Online Help is the content that is delivered as a set of HTML files. The online help is provided for Software-as-a-service, web-based applications, mobile apps, as well as for desktop-based products. It contains conceptual topics, troubleshooting topics, how-to topics, topics explaining forms or fields, and so on. The goal of online help is to provide the needed information to customers to use the product or resolve any issues they face on their own without the need to contact a support professional, saving time and effort.
With the vast variety of topics included in an online help, it has a wealth of information provided in a format that is easy to navigate and includes ability to search. With online help, the cost and manpower required to resolve issues has decreased significantly. It not only provides more information than what might have been needed to troubleshoot the issue but also educates the users on products and services, making the adaptability much easier. As writers, we should make every effort to make the online help not just a document but a tool to support the product.
When creating an Online Help, consider answering the following questions to make it helpful rather than just a collection of topics:
Why would the reader use this topic?
Conceptual topics are written with intent of explaining the why of a feature or functionality.
Who will use this topic?
Consider who is the audience of the content that you are writing. Unless you have the user’s role in focus, you wouldn’t be able to provide the right information or detailing necessary for the topic to be useful.
When would the reader use this topic?
At what point will the user need information included in this topic. This is important to identify placement of the topic.
What steps would the user take to complete the task?
Provide steps in details along with tips and tricks to make it easy for the user.
Where would the user find the information to fill the fields?
Providing separate topics to share content on fields allows you to have dedicated space to provide the necessary detailing for fields (field name, data type, description, usage and behavior). All these pieces of information are critical for user to decide what values can be added to get the desired results. Keeping them separate also benefits the returning users to get to this specific information directly than hunting it within multiple procedures.
Though one cannot sell a product without written help, the quality of Online help might still not be one of the considerations when buying a new product. As writers, we should ensure that the online help system is useful and serves the purpose. Here are few best practices that tech writers should consider when developing online help:
Audience-based writing
A user with a Reporter role does not require same information as an Administrator and vice-versa. So, create separate set of docs or topics tailored to users with varying skillsets and goals.
Doc testing
Topics can get quickly outdated in an Agile environment, where developers are continuously improving or changing the product. Make sure that the documentation is routinely reviewed (technically and editorially), tested (for accuracy), and updated (to match product).
Context Sensitive Help
Provide the help where it is needed. When the user clicks on help icon, the result should provide information for the relevant topic and not just drop the user to a common page.
Navigation and Search
The goal of online help is to make the content easy to find by the way of good navigation or by using keywords to ensure good search results. Both the navigation and search should be user-friendly to aid the users to get to the content.
Examples
There would be no better assistance to the users than detailed examples with working test data. It helps the new users learn the product much more quickly than any number of read through sessions. If the users are able to complete workflows or procedures based on the examples, the adoption of product will rise significantly.