Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Earn badges and make progress

You're on your way to the next level! Join the Kudos program to earn points and save your progress.

Deleted user Avatar
Deleted user

Level 1: Seed

25 / 150 points

Next: Root


1 badge earned


Participate in fun challenges

Challenges come and go, but your rewards stay with you. Do more to earn more!


Gift kudos to your peers

What goes around comes around! Share the love by gifting kudos to your peers.


Rise up in the ranks

Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!


Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

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

"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


Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
Dec 10, 2019

Great article @Michelle Rau good .

Like Michelle Rau good likes this
Samie Kaufman - Your Gal at Gliffy
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
Dec 11, 2019

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. ;) 

Like Michelle Rau good likes this

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.


Log in or Sign up to comment
AUG Leaders

Atlassian Community Events