How to create a great how-to guide for software products with 7 part template

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.

Why are how to guides important – or when to write a how-to guide?

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.

How to create and structure a how-to guide?

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.

Difference of a how to guide as part of software documentation vs generic how-to guide

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.

Ultimate how-to guide template

In the context of a software product, the how to guide could be structured as following:

• Title: should be precise and describe the problem / solution
• Introduction: describe the problem or task with 1-2 short sentences
• Background information: if additional information or knowledge is necessary to successfully progress in the how to guide, add them at the beginning. Keep it short and add links to additional documentation as e.g. product features, glossary or explanations.
• Step by step guide: numbered list, with short description, image/screenshot and additional information whenever possible; if multiple options are available describe them and the impact to the desired outcome
• Outcome and solution: describe in detail what the user reached
• Next steps: if there are next steps in a process, or other related documentation that the user might need – list them here, so the user can proceed and is not lost in the journey.
• Potential problems or questions: if there are common problems or questions that the user might encounter during the how-to guide, add them at the end (and maybe reference at the specific step); this educates the user and lowers your support interactions

How-to guide example

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]

1. Open your browser and go to dashboard [add link to your product’s home page]
2. Click on “create a new project” [add screenshot]
3. Enter title of project (keep it short and precise, …)
4. Define deadline and instructions (add detailed information – e.g. deadline is used on the gantt chart display, user will receive emails when the deadline is approaching, …)
5. User adds mile stones [screenshot, detailed description and link to other documentation types]
6. Add more users and their roles
7. … y

Outcome: the project is successfully created and your colleagues and external users can start working on the project

Next steps?

• How to set up the milestone of a project [add link to specific documentation page, e.g. a how-to article]
• Configure the access rights of a user [add link to specific documentation page]

Potential problems?

• The name of a project must be unique.

Use how to guides to help your user solve a specific problem

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.

Need help creating how-to articles?

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.