"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
👋 Hello Community! My name is Stephanie Zhang, and I’m a product manager on the Confluence cloud team. Today, I’m excited to announce the rollout of Presenter Mode : a ...
Connect with like-minded Atlassian users at free events near you!Find an event
Connect with like-minded Atlassian users at free events near you!
Unfortunately there are no Community Events near you at the moment.Host an event
You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events