How to Write a Good “How-to” Guide (2023)

In a recent article, we talked about steps to writing good tutorials as a developer technical writer. In this article, we want to talk about how-to guides. 

How-tos are very similar to tutorials and are easy to mix up with tutorials. Before now, you probably have never given deep thought to the difference that exists between these two technical content deliverables. 

While the difference might on the surface seem insignificant, on a second and deeper look, you might begin to realize that the difference does matter.  

You must understand that these differences are matters of nuances and that incorporating them would do a whole lot to improve your technical writing skills; giving your technical portfolio a new allure that shows clients or hiring managers that you know your craft.

This difference would also prove super useful for you when you have to manage complex technical documentation with a lot of content strategy decisions.

For instance, you might be tasked with deciding what functionalities of the software to include in creating tutorials, and what part you can just leave for the how-tos. 

Tutorials are mostly created for new users of software technology, and tutorials are a good way to help them get started using the technology. How-tos, on the other hand, is meant for advanced users of software technology.

So you might want to demonstrate the most essential functionalities of the software technology in the tutorials, then cover the less essential ones in the how-tos.

 More on this when we talk about the differences between how-tos and tutorials.

What is a How-To? 

Daniele Procida defines How-to guides as “directions that take the reader through the steps required to solve a real problem”.

How-tos are problem-oriented in nature, in contrast to tutorials that are learning-oriented in nature. 

A good way to help you understand this difference is to think about how you approach learning a new software technology as against getting around a roadblock when trying to perform a given task.

For instance, you are new to the Django framework. At this point, you will not be worried about executing a particular task using Django built-in classes and mixins. You don’t know anything about the framework, so you are incapable of asking these specific questions. Instead, you will be concerned with getting familiar with the framework.

To do this, you won’t be consulting Stackoverflow, as it won’t be a useful learning experience. Most answers would assume too much knowledge from you. 

Instead, you would consult Django official documentation or other getting started tutorials, which would prove a better learning experience as they would help you know the essentials of the technology and help you get comfortable and build simple first projects with the framework.

But let’s assume differently you are already familiar with the framework. Familiarity means you are aware of the Django framework. You know what can be done with it and what can’t be done with it.

In this case, your concerns would be different: you would be concerned more with exploring how to use the various Django built-in software components to solve specific problems or implement specific tasks within a Django project. For instance, how to implement an e-commerce product page using Django ListView.

Stackoverflow would be very useful for you in this case. There, you will find help from other members of the platform who can help you with solutions to solve that problem. 

In other words, you can think of Stack Overflow as a platform that hosts a lot of how-to guides, though in a less organized and untidy form.

Rules for Creating Good How-to Guide 

Describe a Sequence of Steps

Unlike tutorials, how-to guides are not end-to-end guides.  They don’t start from the beginning; rather, they begin at medias res (in the middle of things) and describe a series of ordered steps in order to arrive at a reasonable stop.

You want to keep in mind that readers of how-tos are usually in the middle of executing a much bigger task than the problem they are facing, so they expect you to provide a solution to just that problem. 

They don’t need you to elaborate on what they already know.

For instance, you need to implement an e-commerce payment page with Stripe API on Django. It would defeat the purpose of the how-to if the technical writer of the how-to guide starts from the beginning: teaching how to create a Django project, a Django app, setting configurations, e.t.c.

You most likely would scroll past all these sections to the part relevant to the problem you want to be solved. This could also prove frustrating if you are not able to find the relevant section quickly.

Stick to One Problem 

Your goal with a how-to guide is to attend to a particular problem. If you need to attend to two problems, then you need two how-to guides.

The flexibility you are allowed here, however, is that you can provide more than one solution to solving the problem. 

Your approach to ordering the solutions is subjective to you. For instance, you could decide to order the solutions from the most simple to grasp (though less efficient code) to the more difficult to grasp (more efficient code).

This is also one area that distinguishes how-tos from tutorials. With tutorials, there must be no alternatives to getting tasks implemented. This will confuse the learner as the goal is to get them familiar with the technology.

With how-tos, the goal is to get the learner to become an expert on the technology, so providing several alternatives or ways to solve the problems would be very useful in achieving that.

Then, you might also want to think about scenarios where you want to demonstrate the usage of the different functionalities of software technology.

 If your goal is to demonstrate the usage of a single functionality in solving a particular problem—for instance, how to create a Django Custom Manager—then it would make sense to use a how-to guide over a tutorial. This is one of the many use cases of how-tos.

Don’t explain concepts

Just like in tutorials, you should not explain concepts in how-to guides. This reinforces what I have already asserted: focus on the problem and the steps to solving it.

If there is any need for the reader to have a grasp of certain concepts in order to use the how-to, then you can consider placing them in the prerequisites—or right at the place where they occur in the how-to—with links to the resources that provide explanations.

Difference between How-to Guides and Tutorials

How-to guides do not create a learning experience for a reader. 

Perhaps, it would help to make this even clearer. A learning experience takes place in a contrived setting where the reader/learner is placed in a very comfortable learning environment.

There are a lot of hand-holding exercises. There are no surprises, and every aspect of the learning experience remains predictable for the learner. In short, you can think of it as babysitting. 

The learner is not expected to feel responsible for anything. It is totally the responsibility of the teacher to ensure the learner understands what is being taught. This is exactly what a tutorial does.

And how-to guide, on the other hand, is just that: a guide. It guides the work of the user. It offers no learning experience as it assumes some level of knowledge from the reader.

There is no hand-holding involved. All it does is direct the reader in the right direction to get the problem solved.

So a how-to guide is leaner, more focused, and straightforward than a tutorial. While a tutorial will be explicit with basic things (which makes for bulkier content), a how-to guide assuming implicit knowledge will make for leaner content.

Secondly, a how-to guide does not seek to familiarise the user with the software technology. And this is why you don’t create end-to-end how-to guides. You can only have end-to-end tutorial guides.

Summary

If your software documentation is good, then your tutorials should have done perfectly the job of familiarizing users with the software technology. The how-to guides are meant to build on top of that. They are meant to help the user master the software technology beyond the bare minimum and the basics.

So that’s it on how to create better how-to guides. 

Comment for more clarification and if you find it useful.

Contentre helps technical writers stay organized and gain more clients. Grow your technical writing career in one place.

Now that you’re here, let me briefly recap the most important features Contentre can offer you:

• Organize your content in categories, topics, and tags
• Create and manage multiple clients
• Create and manage multiple personalized portfolios
• Get statistical analytics of your content revenue, top categories, and tags.

Try it now. It’s free