From Nerd to Normal: How to Write Better Help Articles

by | Technology

By Mat Bradley-Tschirgi

Everyone’s had that moment when you are using an app and then get stuck. You go to the company’s website, and click on the dreaded “Need Help?” link only to find a vague post written for nerds instead of neophytes. You can’t make head or tail of it. After a few more minutes of fruitlessly searching, you give up.

Online help articles don’t have to be this way. With these easy tips, you’ll be able to help users in a clear fashion that will result in greater customer satisfaction and fewer support calls.

Short Articles Are Better than Long Ones

People have less free time than ever before. Between checking your Twitter feed, LinkedIn followers, watching the latest Netflix series, and listening to an album on Spotify while gobbling down dinner, it’s a miracle if anyone reads your article to begin with. Going in with tightly focused articles released in a steady stream on a regular basis (say, every Thursday afternoon) is preferable than releasing a rambling tome of a tutorial.

For instance, if you were trying to explain how to use the login page of Facebook, you might break this out into four separate articles instead of one big one:

  • How to log into your Account
  • How to reset your Password
  • How to Create an Account
  • How to access the Help page

Learn to Love the Screenshots

As James Lafferty said, “The picture alone, without the written word, leaves half the story untold.” People need pictures with text to better grasp a concept. Don’t be shy about using oodles of images in your writing to accentuate the point you’re trying to say. For example, an article on “Resetting Your Password” might need only three images: the “Reset Your Password” link, the email itself so the user knows what subject line / etc to use, and the final page where you do the actual password resetting.

Markup your images with arrows or circles to help point the user in the right direction. Techsmith’s Snagit or Windows built-in Snipping Tool are both fine choices to help mark up your images to nudge your readers along.  

Use Clear, Direct Language with a Friendly Tone 

So you have some nice images for your article. Great. Now you have to write the darn thing. You’ll want to write in a such a way that gets to the heart of the matter. Be direct, simple, and clean with your language. You want to get in, state how the user can accomplish whatever goal they are doing as fast as possible, and get out. Don’t ramble with asides about your favorite episode of Million Dollar Listing New York.

At the same time, your writing shouldn’t be too technical or too stuffy. It can be a little playful while still meaning business. It might take time to nail the tone you’re going for. Once you have it nailed down, consider writing an in-house Style Guide to encourage a uniform style among across all your help articles regardless of who is writing them.

Use Inspiration from Actual Support Tickets

Whether they are in the cloud or on an iPad, apps are more complicated than ever. Even something like Microsoft Word has several dozen menu options to choose from, most of which have sub-menus with dozens of more options. With that in mind, where do you start when planning out what help documentation to write?

Spend a few hours to do a rough analysis of support tickets from the past three months. What are the top 25 common issues? Resetting passwords and minimum software requirements are always a good place to start. The process of writing a comprehensive library of public facing help articles can be a long haul, but is worth it in the end.

Crosslink to Related Articles

Quite often you’ll be writing an article that references something else. For instance, you might be telling the user how to open a contact and have an aside telling them “to open multiple contacts, check out this article.” Whenever this happens, provide links to the other articles. This allows the user to have a more seamless experience leaping from related article to related article instead of going all the way back to your index page or searching a new term every time they need to find something.

Have a Support Number Handy on the Page

Every help article you read should have your technical support phone number and/or email available at the bottom with a caveat like “For additional help, please contact our Customer Success department at xxx-xxx-xxxx or through our Submit a Ticket page.” While you’re not discouraging people from calling your customer support staff, you are teaching them to fish with the hope they will be engaged in learning from your help articles and spread their knowledge to others in their company, etc., etc., etc.

Don’t Talk Down to the Customer

Users of your app or website come with all types of computer skills. Some people might consider themselves a computer genius with small g. Others might not know what a web browser is. Regardless of the user’s skillset, you want them to have a good experience using your app. You want to strike that careful balance of not being condescending but also not assuming everyone is a computer expert. If in doubt, it can help to have another user read through your document walking through the steps and take notes if any questions come up. Your knowledge base of help articles is a living, breathing document. Treat it as such.

Ready for Your Next Job?

We can help! Send us your resume today.


Need Talent?

Submit your job order in seconds.


About ProFocus

ProFocus is an IT staffing and consulting company. We strive to connect a select few of the right technology professionals to the right jobs.

We get to know our clients and candidates in detail and only carefully introduce a small number of candidates that fit the role well.