We’ve all encountered Help media that is, shall we say, less than helpful. Videos that maintain a far zoom when a close up of the part of the project currently being worked on would be more informative. Help documentation without screenshots that also doesn’t give any directional information. It leaves the reader asking, How do I get to the menu the next 15 steps tell me about? Where do I click? Did I miss a step? And readers aren’t asking themselves, they’re asking the Help doc writer!

The number one commonality I’ve seen in “bad” Help media is that it’s created by the Subject Matter Experts (SMEs). They understand how to get to that menu, what the precise tools and materials they’re providing the steps for look like and how they need to lay out, so all they need to tell you is what to do. They have an image of the system or their workshop or jobsite in their heads that is absolute (the what), so providing associative steps (the how and when) doesn’t even occur to them.

• Click the second link above the main body of the page
• From the drop down menu that that opens, click the 3rd item listed, called This
  • If This isn’t listed, go back two steps to make sure you’re in the right screen

And that’s the problem with having the person most knowledgeable about the subject produce the Help media. The SME has the accumulated knowledge and can assume those associative details. The “newbie” has no such accumulated knowledge and is left wondering, “is it broken or am I?” Ahem. “Is the system broken or am I missing something?”

Product Managers make good Help doc writers because they basically never grew out of that toddler stage of asking “why?” all the time. And one step past Why? is How? One step past taking notes to remember How? next time is adding in those little details that the SME assumes, meaning, knows like they know their own names. Personal how-to steps for the newbie read more like:

How to do the thingie
Step 1: Login
Step 2: Find the relevant menu on the 1st screen after login
Step 3: Click this thing. It’s not the name of the thingie but it’s what I need to click to get to the thingie
Step 4. Do the thingie
Step 5. CHECK EVERYTHING
Step 6. Save
Step 7. CHECK EVERYTHING AGAIN
Step 8. If something is wrong or goes wrong, call Steve. If he solves it/ fixes it, remember: He hates chocolate (weirdo) but his wife loves white chocolate (double weirdo) and you can bribe/ thank him with a small baggie of Lindt white chocolate truffles. See bottom drawer for bribes/thank you gifts.

Nothing is assumed, even in text-only media.

I guess what I’m saying is, write like a n00b. It’s one of the most fun things about being a technical writer, to me: we get to become quasi-SMEs for a minute, but because that process is fresh in our minds, we document everything and assume nothing (or if we do, we document what we’re assuming). In that way, we produce content that is instructional for the newbie and a reminder for the casual user and make the true SMEs say, “okay that’s not the complete business logic behind that, but as far as the steps to take at this stage, it’s technically correct.”

And hey, this is Technically Writing.