How to guides are a helpful tool to create good user documentation for your readers and users. They describe how to solve a need or problem with simple steps.
Use a how to guide to instruct your user and reader to solve a specific need or feature. You exactly describe the necessary steps one by one.
Screenshots are used to guide the user. Detailed instructions can be added to provide background knowledge why the step is necessary.
If multiple options are available, they are described – so the readers can decide which one to choose.
According to wiktionary, a “how-to” gives advice or instruction on a particular topic, or a brief informal description of how to accomplish a specific task.
There is a lot of variances and different options how to make the perfect how to document as part of the user manual and guidelines.
It should be short and specific to the target audience. Use the terms a reader will see on the screen or might use in the daily (business) life.
Do not make it too complex, or mix with other tasks. Use simple words in the writing.
If possible, the writer adds screenshots and related background information.
If additional information is necessary, link or reference it at the beginning.
Describe all options and the impact to the output the user will encounter during the solution steps.
If there are related articles, tutorials, how to guides and other documentation types, add links to them.
There is a lot of information on the internet about generic how to guide for websites, articles, blog posts, Instagram or Facebook. This is mostly used to write generic instruction for different kinds of practical advice. The goal is to get as many visitors from outside and solve a specific need.
The difference to a software how-to guide as part of the software documentation, the goal is to solve the specific needs of your user base and target audience. It can be visible in the search engines and public to the internet. Most of the visitors will come from your SaaS or other software application during the build-in search, your documentation software or knowledge portal or from a link inside your web application.
Your goal as technical writer is to educate the user as fast as possible so she can continue using your app and reach the desired goal in the shortest amount of time without any issues or problems.
In the context of a software product, the how to guide could be structured as following:
For example, to setup a new project in your project management tool, the author and technical writer could use this example as a starting point. It is fictive and very short to demonstrate the main elements of a how to article.
Title: How to create a new project
Introduction: The project is the main element of our [your product name] and structures different work packages into a specific element.
Background information: our philosophy of project management [add link] describes how we handle projects at [product name]
Steps to create a new project at [product name]
Outcome: the project is successfully created and your colleagues and external users can start working on the project
The howto guide or how-to article is an important documentation type for software products. It helps the user to reach the goal and educate it during this journey. It must result in a success – otherwise the experience will be negative.
Keep it clear, short, precise and to the point. Use the same words as on the pages the user interacts with. Link additional information to educate novice users. Make sure the user succeeds.
If you have a question or need some more information, reach out to us. Subscribe to our newsletter to get more information and content about multilingual documentation.
This page is part of the comprehensive list of documentation types.