Roadmap or atlas? 5 ways to provide context to your how-to readers
Way back in the 1990’s, when I was building early, early web applications, I was told that I needed to build my website on an application called Oracle Web Application Server. Nobody I worked with knew anything about it, but that didn’t faze me; I specialized in learning things.
And there was plenty for me to learn. I learned that I needed a language called PL/SQL. I learned everything about the syntax, from how to declare a variable to how to perform complicated database operations using a construct called a cursor. I became an expert in how to create web pages using PL/SQL.
There was just one problem: I couldn’t find a shred of information on how to actually run PL/SQL on OWAS.
In other words, all of that detailed information was useless without context.
It was like getting extremely detailed directions to a meeting, from the streets you should drive down to the parking lot in which to leave your car to the elevator to take up to which office — but not knowing what city the meeting is in.
One of the things that makes tutorial-creation interesting is that not everyone learns the same way; some of us are audio learners, while others have to see what you’re talking about. Still others need to actually do something before they understand it.
When you create how-to content, you must go out of your way to provide context for the user. Remember, if they knew everything you know, they wouldn’t be consuming your content.
Fortunately, you have lots of options for providing this context.
A picture is worth 1000 words
Oftentimes the simplest way to provide context for your users is to provide an image that explains what you’re talking about. This might be because the process is complicated, but even simple concepts can often benefit from a graphic of some sort if you need to explain how a particular concept fits into the big picture.
For example, at the time that I’m writing this, I’m also putting together a free web course on writing tutorials. To fill that course, I’m using Facebook ads, and I’ll eventually write that up as a case-study on how to promote your content. But when i talk about, say, “Lookalike audiences”, it’s a concept that doesn’t stand on its own, so I might use a diagram something like this to explain where it fits in:
A 1% lookalike audience consists of the 1% of the target country that most closely resembles the source audience, such as people who like your page or who have visited your web site. You can use a lookalike audience to expand your reach to those in other areas who are most likely to be receptive.
If you are going to use a diagram or other visual, make sure you don’t assume that it stands on its own. So in this case, I’d explain how lookalike audiences are based on people who’ve engaged with your content and can be used to expand your reach to like-minded individuals, and so on.
Show your work
I started out as a technical writer, so I’ve spent vast portions of my life explaining bits of programming code, and one of my pet peeves is when writers are careless in this particular step.
Large blocks of code can be incredibly opaque, so it’s up to you to make them clear. As a reader, which of these two examples would you rather see?
Example 1:
<html> <head><title>My home page</title></head> <body> <h1>Sharks with frickin’ lasers on their heads</h1> <p>Actually, this weekend I finally got a shark with a frickin laser on its head. True, it’s a laser pointer, but still, I love it.</p> </body> </html>
As you can see, in this example, I’m starting out with an HTML tag, and I’m adding a head and a body. In the head, I’m adding the title, and in the body, I’m adding the actual content.
Example 2:
- Start out with the main html tag:
<html> </html>
- Add the head, which includes the page title:
<html> <head> <title>My home page</title> </head> </html> - Now add the body:
... </head> <body> </body> </html> - Finally, add a heading (
h1) and a paragraph (p) to the body:... <body> <h1>Sharks with frickin’ lasers on their heads</h1> <p>Actually, this weekend I finally got a shark with a frickin laser on its head. True, it’s a laser pointer, but still, I love it.</p> </body> </html>
Now, I guarantee there will be some of you saying, “I like example 1 better because I can just copy and paste the whole thing.” And there are times when that’s appropriate, if you’re looking for a quick fix for something you’re not likely to encounter again. But as tutorial authors, we need to remember that good tutorial content actually teaches the reader — and as an author, we always have the option to provide a link to the complete example as well as the readable chunks.
Let’s go to the videotape
For those times when a single picture won’t do, consider embedding video in your content.
Videos are great when you’re explaining the steps to do something, and are particularly useful when the steps aren’t obvious. This might be because the task itself isn’t something a person might ordinarily do, or it might be because the items your audience needs to interact with aren’t in an obvious place.
If you’re describing how to do something online, consider adding a quick screencast that explains the process; if it’s a physical process, you can often get a decent video with your phone rather than having to go through a lot of trouble.
The important thing here is to remember that the object of the video is to provide context to your audience; focus on that rather than on details that aren’t necessarily relevant to the big picture.
Explain it to me like I’m five
One of the most important things to remember is that your audience wouldn’t be coming to you if you didn’t know more than they do, and as long as you’re providing all of the information they need, they will never complain that you’ve made things too simple. (That’s not to say you want to be condescending, of course.)
For example, I’m currently working on a computer programming technology called Kubernetes, and I’m in awe of Matt Butcher’s Children’s Illustrated Guide to Kubernetes. It’s a technical topic in the style of a children’s book, and I learned more from it in 15 minutes than I had from days of trying to cobble together concepts from the Internet.
Moreover, once I’d learned the concepts from Matt, I was able to go ahead and apply them to the specifics of how to actually do things with Kubernetes.
Go ask your mother
There is one situation where you not only can assume a certain amount of knowledge on the part of your audience, but in which you should, and that’s when your content is specifically intended for those with a more advanced grasp of the topic.
Knowing your audience is important, and there’s no reason to bore more advanced readers with the basics. You still need to provide them the appropriate context for their level, of course, but what do you do about those who’ve wandered in and might not be ready for you?
In this case, one solution is to simply provide the audience resources they can check out to get the foundational knowledge you’re assuming they already have. You can do this in the form of pointing to documentation, to other tutorials, or (even better) to cornerstone content on your own site.
Where to go for more
I believe in following my own rules, so if you’d like more information on the overall concepts behind putting together tutorial and how-to content, I’d love it if you joined me for that free class I was talking about earlier. We’ll be talking about all of the steps you need to understand, from choosing a topic to promoting your tutorial after it’s done. Sign up here!
