Before you begin: the power of Step 0 in a how-to

[#1]

"I appreciate that the directions are there," Bob* said, "but they assume things I don't know yet."

I nodded my head in sympathy, pencil poised over my notepad. I'd come to talk to Bob about the comments he'd posted on one of our lab's wiki pages. He'd finally found the information he needed, but only after running a command that everyone seemed to know about but him.

I could relate to his frustration. New to the lab, there were lots of acronyms, terms, processes, conventions, languages and tools that I didn't know. I thought this was because I'm not a developer or coder, but Bob was an experienced developer (though new to the lab too) and he didn't know everything either!

I took a careful look at the many how-to pages in our lab's space. Bob was right. There were plenty of how-tos, and good instructions, but reading them was a bit like stepping into the middle of a conversation. Then I looked at the how-to template in our space. Sure enough, it started with "Step 1."

What we needed was a "Step 0" -- what needed to happen before someone could actually start executing on the steps in the how-to. Tenured developers tended to jump right in at Step 1 or even Step 2, having all the essential scripts, tools and access already set up. But those new to the lab wouldn't necessarily be as well-prepared.

Fortunately, our subject matter experts who wrote the majority of the how-tos were already familiar with the how-to template. So I added a simple section to the top of the how-to template: "Before you begin."

Before you begin
List anything a reader will need to know before they begin executing the steps in the how-to. Include things such as:

• Specific product, version, technology or operating system the how-to pertains to or requires (example: "These steps are for Windows 7 or Windows 10.")

• Software, hardware or tools that may need to be installed or run (example: text editor, special cable, script, etc.)

• Access such as to a code repository, permissions, website, portal, wiki space, token, etc.

• Assumptions about reader's knowledge or experience ("This article assumes you are already able to ____ and ____.")

I hoped this would encourage how-to authors to take a moment to reflect on how to make their instructions beginner- or outsider-friendly. The list wasn't meant to be all-inclusive, but a suggestion to consider what was necessary. Even if the how-to author decided to remove the "before you begin" section, it would still serve as a reminder to consider the next reader's experience. They were already inclined to, I thought: after all, isn't a how-to by definition for someone else's benefit?

The results were positive. Since the template change, at least a dozen how-tos included the new "before you begin" section. Other how-to authors skipped the list, but helped set context by adding disclaimers, Q&A about the tool, background or explanation, or prerequisites. I've shared the "before you begin" template as a best practice with our local wiki users. Feel free to adapt it if it could benefit your users as well.

* not his real name

[Kat Warner]

Great article @Michelle Rau HP .

[Samie Kaufman - Your Gal at Gliffy]

Love the "step zero" idea here. It's like when you get furniture from IKEA and they want you to check that you've got all the parts before you start constructing. Or like a recipe — you want to make sure that you've got all the right tools and ingredients before you get halfway through making something. ;) 

[Christianne vd S]

I agree. I started in a manufacturing environment 10 months ago after working in business services for over 10 years. It's taken me a long time to figure out the Step 0's for my job and I think it would benefit everyone to have this simply tacked on to a manual or a how-to article.