My podcast addresses some mistakes writers commonly make when creating how to articles.
What is a how to article?
A how to article helps the reader to accomplish a specific task. This may be a technical task such as loading a new computer application, a mechanical task such as changing the oil in a car, an educational task such as writing a research paper, or a more esoteric task such as ending a relationship or meditating. How to articles are often called instructional or procedural articles. One of the oldest and most common types of how to articles is the recipe. A good recipe contains all of the key components to a good how-to article.
- A well defined goal (bake a cake)
- Necessary components (ingredients and tools)
- Steps (mix sugar and flour, add eggs)
- Conditional changes and options (Adjust for higher altitude, substitute brown sugar with molasses)
- Expected result (cake should be moist and golden brown)
How to prepare for a how to article
Identify your target reader
Think about who is likely to use the instructions you’re about to write. Are they experts? Are they totally new to the process? Are they, like most of us, somewhere in between? Are you writing in their native language as well as yours or will you readers be doing some mental translating? You may not always know exactly who you’re writing for but keep your reader in mind as best you can; aiming at a specific type of reader will inform your article from beginning to end.
Define the goal
Defining a goal is not complicated, but it does take more thought than most people give it. The main thing to remember is that there is a direct goal and an indirect goal. The direct goal of a person who reads an article about “How to Brew Beer” is to brew a beer, but their indirect goal is to create something that they can then enjoy and be proud of. Most how to advice is a means to an end. The reader wants to accomplish the task, but their real goal is the result of that task. An article about How to eliminate the XyXIX virus from your computer will be used by people who want their computer to work properly. Getting rid of the virus is just the means to an end.
Define the standards for success
One of the reasons you should spend a little extra time thinking about the reader’s goal is because it will help you define your standard of success. The standard of success is the expected result of your how to article. You are defining the result that the reader will expect to produce by following your instructions. For example, if your reader is attempting to build something, the standard or success might be that the end result is:
- Functions properly
- Required only the supplies and equipment specified
- Built within economic expectations
- Finished without personal injury
- Holds up to the stress of use.
Walk through the process
When creating a how to article, you should expect to do the task you are documenting. You don’t tell someone how to bake a cake unless you can bake a cake. The key to a successful walk through is to track each step you take and the result of that step. Steps should be broken down into small, clear actions that produce a result.
In some cases, it may not be possible to replicate the entire process. Due to exterior constraints, you may not be able to perform every step of a process. For example, when documenting software that is still in production, you may have to assume a result. This is especially true when working with dummy data (information created for simulation purposes) or with mock-ups (graphic representations of the expected final product).
Examine the options
There is more than one way to accomplish most tasks. For example, many computer commands can be accomplished with either the mouse pointer or with keystroke combinations (often called shortcuts). Additionally, part of the process might change based on your choices. Option A might have different steps than Option B. Depending on what you are writing about and who you are writing for, you will have to choose between telling your reader a single way to accomplish a task and discussing their other options. This is particularly true when you’re describing how to do something technical. Installing software often forces the user to either accept defaults or to make fairly sophisticated decisions. Building a shed would present choices such as where you put a door; that choice, when made, results in the need to be sure the right sized shelves go in the correct place, etc.
Consult an expert
Writing a guide to a process you are not expert in can be a challenge. That is why it is important to find outside resources to help you write your article. Subject Matter Experts (SMEs, called smees) are a great resource in this situation. A SME is simply someone who has the information you need in order to properly write about a task. At software companies these are often product specialists, programmers, trainers and business analysts. It is certainly easier to write a how to article when you are the expert, but even when you think you know all you need to know, don’t underestimate the value of a second opinion. There may be a better way to do things and it’s almost always true there will be a different way to do things. Chefs, for example, often change a cake recipe to complement an entrÃ©e.
Research what others have written
Additional research is always a good idea. No matter what topic you are writing about, there’s a good chance someone on the Internet has tackled something similar. In the software world, there are usually archives of supporting documentation such as functional specifications, business reviews, quality assurance scripts and usability testing results. Looking over the information that is out there can be a real help in making sure your article is a good one. You don’t need to read every article or brief though. The number of ways to bake a cake is astronomical. You could spend the rest of your life just studying cake recipes.
A brief style guide for how to writing
Order and grouping
How to guides are written in a procedural format. That means that you follow a logical series of steps. Depending on the topic, you may or may not need to number these steps. In general, the less technical or mechanical a topic is, the less need there is to number steps. This article is not numbered because each step required considerable advice and discussion, and because the order of events is not fixed. While you can write a how to article following these topics in order, it is not necessary. There is no real problem is you consult an expert before you define the audience or examine the options. In fact, it may be the better way to do things in some cases.
There are often pieces of information that belong together even though they don’t have a specific order. A list of supplies or a list of resources, for example, does not need to be in a specific order but should still be grouped together.
Ordered list (numbered list)
Most ordered lists are numbered. In general, standard 1, 2, 3 numbering is best. Some documentation styles call for roman numerals or letters, but those are the exceptions. Lists tend to become more complicated, however, if you need to document sub-steps. This can happen if you have one or more options to choose from and need to describe how each option produces a particular result. A list with subsets is what is referred to as a nested list. For nested lists, letters are often used instead of numbers.
Try to keep the number of steps in an ordered list under ten. Readers tend to be intimidated by longer lists. To shorten the number of list items, you may want to break a complex task up into two or more sections/parts. This can often be done by finding a logical place to begin numbering again following a paragraph of explanation.
Unordered lists use bullet points. A bullet point is a dot or a square (or other design) before a list item. Unordered lists are great for article elements such as lists of tools, supplies or options
If a step in the process changes the situation (creates a result), that needs to be documented. For example, when someone clicks on a link online it will generally send them to a new web page (or at least change the look of the web page they are on). Another example might be when the step is adding, say two eggs to the flour, butter and sugar in the cake, a description of how the batter will change (become more liquid) would be appropriate. Describe the result immediately after the step, but do not make it a numbered item because it is not a separate step.
References and resources
When working with outside sources (such as information from books or other web sites) be sure to acknowledge those resources. When possible, provide a link to the source material. Doing this not only gives fair credit to the source author, it also provides additional information that your reader use clarify questions and provide alternatives.
When writing a how to guide, your overriding goal should be clarity at all times. This style of writing isn’t as broad or imaginative as prose. You want your statements to be direct, concise, and unambiguous.
Short sentences are almost always preferable to long sentences when you are writing a how to guide. Short, declarative statements make for good steps. Never try to combine two steps into a single sentence.
One of the keys to writing a procedure is to use the same words in the same way every time you use them. Some words, such as Run and Program have many meanings. When you write a guide, you don’t want to have your words misinterpreted, so do your best to use the word consistently to mean one thing throughout your instructions.
Just as you want a word to mean the same thing every time you use it, you want to use the same word every time you mean the same thing. If you said, run the program the first time, don’t say start the application the second time.
Additionally, use the same phrases when an action is repeated. If you write, Click on the OK button the first time, don’t write Click OK the second time. Use the same phrase every time.
Accurate and unambiguous words
Using unambiguous words will help your reader understand your instructions. Here is an example of a set of terms that become increasingly unambiguous:
- Communication device
- Mobile phone
- 3G capable smartphone
- Blackberry smartphone
- BlackBerry Curve 8900
In the world of cooking, stirring had a different meaning than beating or whisking does. Use the most appropriate word and use it consistently. If you’re not sure what word is best, look it up or ask your expert.
Add Supporting Materials
When documenting a computer-based process, screen shots (images of the screen) are an excellent way to demonstrate both the steps to take and the results of those steps. There are, however, a few drawbacks to using screen shots.
Screen shots take up a great deal of space on your screen or page. It can be difficult to find a balance between the clarity of the image and the amount of space it takes up. These space considerations can be especially troublesome when you are working with mobile devices such as smart phones and touch screens.
Screen shots can be slow to load. Image files take longer to download and display on a screen.
Screen shots can become outdated. I once worked on a project in which the previous writer had meticulously created screen shots complete with additional graphics such as pointers and numbering. When it came time to update the document, all of those screen shots were useless, even though much of the underlying process remained unchanged.
If the screenshot is to be printed, make sure it will be large enough to make it worthwhile. If it’s an ebook, the chances are the color on the screenshot may get lost if the user prints it â€“ you can solve this by making the shot grey scale to begin with.
When you are writing about a physical task such as putting a desk together, illustrations tend to make the task much easier. Many people think visually, and a good illustration can really clarify a process. Like screen shots, illustrations can sometimes become outdated. The main downside of illustrations, however, is that they take drawing and design talent. If you don’t have these talents (or have someone who does) then this will take a lot of time and may never produce the desired result.
A flowchart is a great way to clarify a process. This is especially true if the process has many optional steps or choices to be made. The symbols on a flowchart each have a set meaning/purpose, so you will want to get a good idea of how they work.
Slideshows and video
An accompanying video or slide show presentation can be very handy for your audience.
The first step in testing is to follow your own how-to instructions. Do exactly what you say to do. Don’t let yourself stray from your written plan. If you do, then it may be a gap in the article.
The best way to test your instructions is to have several people actually try to install the software or bake the cake or put the desk together. It is particularly helpful to watch people as they are testing your process. They may complain that step 5 is confusing, but that may only be because they made a mistake at step 3. You won’t learn that just by listening to or reading their feedback. You’ll also see where they hesitate and re-read the instructions. Often, however you’ll have to make do with their notes. And sometimes you simply won’t have the opportunity to test.
Having someone new to the project read through your instructions can help. They may spot something that’s crystal clear to you but incomprehensible or confusing to them.
The final result
A well-written how to guide should have the following qualities:
- It should be easy for it’s target audience to understand
- It should have a clear result
- It should accomplish the stated goal
- It should have all the information necessary for success