Writing Great Tutorial and How-To Documentation

Writing great software tutorial or how-to documentation can be a kind of art form. It takes great writing chops to put the correct words on paper, but it differs from traditional writing in that it is not usually advisable to just write.

Technical writing, instead, is far more about the planning of your piece.

One way to look at the planning phase of writing tutorial or how-to documentation comes in the form of the 5 Ws… and an H.

This ‘W’ covers a lot.

At its core, it can be viewed as who will be using the software and thus the documentation. However, it can expand even further and potentially even more importantly.

Teams also need to think about their maintenance review plans for their documentation. While it is important to organize the schedule (whether that be semi-annual or annual), they also need identify who will be in charge of conducting the review and who may be impacted if a revision is made to the documentation.

Prompt updates and notifications of said updates are key. Pre-planning to ensure these tasks are completed timely can save a world of trouble should outdated documentation be used or team members spend unnecessary time verifying themselves if the changes were done intentionally.

Another important step to writing effective documentation is by identifying what the document is covering and letting the reader know.

Depending on the document being written (whether a tutorial where we assume a beginner or a how-to where we assume they have a base understanding), it is still commonly advisable to focus on two key parts of tackling the what.

The first key part is the title. The document title should be clear and concise in plain language. For example, “How-to Update Your Billing Information”.

The second key part is the introduction. An introduction should be short and sweet and should identify the task, the module, and end result. Ideally, this should be accomplished in around three to five sentences. If you feel additional background information is warranted, think about writing a separate explanation document and include a link to it.

A principle I have always lived by is that to fully teach someone how to do something they need to understand why. Folks can memorize steps and still achieve the correct results, but their lack of tolerance for inconveniences such as a 1% difference in input can result in them not fully understanding required steps to right the course of the process.

Thus, when writing your documentation, think about the steps you will include and, where applicable, tell the reader briefly (one to two sentences at a time) why they must do this step or why the software works the way it does.

It is advisable to make this clear if it is critical that a step is not skipped.

Likewise, when a revision is put into place and notification to teams is completed, explain why the revision was made. This extra information will help team members remember, buy into a process, and help them feel comfortable that they are using the correct procedures after a change has been made to their workflow.

Documentation must also identify where a reader needs to be in the software they are using to complete their tasks.

You may choose to include this more generally within the introduction of the documentation or more specifically within each step. This will be dependent on if the process will take the reader throughout multiple screens.

Another key component is to identify the timeframe for a process. In software, there may be key maintenance tasks that must be done during certain business hours or on say the first calendar day of a month.

It is critical to make this information clear to the reader to prevent issues with incorrect processes or missed processes.

Lastly, the meat of all documentation. Any good tutorial or how-to documentation needs to tell the user how they can complete the process and achieve their end result.

These steps must be clear, logical, and written purposefully.

These steps may differ depending on if a tutorial (where we assume a beginner is reading) or a how-to guide (where we assume the reader has base knowledge) is being written.

If writing a tutorial, be more specific and hold the hands of the reader. Make use of additional documentation, but sparingly enough that it does not hinder the flow of the user’s learning.

IF writing a how-to guide, be specific in your steps, but use additional documentation more heavily so the reader is able to focus directly on the steps in your documentation without extra content they may not need on the page if they are more experienced.