Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Deleted user
Level
0 / 0 points
Next:
badges earned

Your Points Tracker
Challenges
Leaderboard
  • Global
  • Feed

Badge for your thoughts?

You're enrolled in our new beta rewards program. Join our group to get the inside scoop and share your feedback.

Join group
Recognition
Give the gift of kudos
You have 0 kudos available to give
Who do you want to recognize?
Why do you want to recognize them?
Kudos
Great job appreciating your peers!
Check back soon to give more kudos.

Past Kudos Given
No kudos given
You haven't given any kudos yet. Share the love above and you'll see it here.

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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

3 comments

Kat Community Leader Dec 10, 2019

Great article @Michelle Rau .

Like Michelle Rau likes this

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

Comment

Log in or Sign up to comment
TAGS
Community showcase
Published in Confluence

⚡️NEW Group for Confluence Cloud Admins

Calling all Confluence Cloud Admins!  We created a new Community Group to support your unique needs as Confluence admins. This is a group where you can ask questions, access resou...

133 views 2 10
Read article

Community Events

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

Events near you