4 Help Authoring Mistakes Technical Writers Should Avoid

Help Authoring

The first time I heard this highfalutin sounding word “help authoring” it was a profoundly excruciating experience. That was a time when I was just starting out on my journey as a technical writer. But now the word doesn’t seem so daunting, in fact, I feel these two words succinctly sum up the essence of what documentation should mean i.e. to offer HELP.

At times, when we write documentation, we tend to drift away from this central concept i.e. to provide the content that can best help an end user (customer usually) to understand your product or service.

This is the reason why I am writing this blog post, to humbly share some errors that I have made in the past and how you can avoid them.

So let’s begin....

Mistake 1# Not beginning with examples

As technical writers, we suffer from the affliction of too much information but less clarity. What I mean is that when we are writing about a topic, which could be a new product feature, a technical guide for developer etc, we begin with a thorough understanding of how the thing works.

But our readers don’t. In fact, most of them come to read the documentation because they have little knowledge about the feature or topic.

The best way to bridge this gap is to provide an example right at the beginning. This could be possible scenarios, use cases and situations which are customer-centric and not feature specific.

Recommended Read: Best Practices for Creating Knowledge Base Articles

Mistake 2# Not interlinking related articles

While most help authoring software come with inbuilt features that automatically create related articles list, it’s usually at the bottom of the page or on the side panel. However, this is not as helpful as a link right in the body of the article would be to readers.

At times, customers tend to ignore the related articles and they end up raising a support ticket because they find your documentation unhelpful. Not linking phrases or keywords, that need further explanation, to related help articles should be treated as a cardinal sin by technical authors.

Mistake 3# Not using images or illustrations

As corny as it may sound, the saying that an image speaks a thousand words is a truism, which technical authors would better do to not ignore.

Explaining concepts with relevant images, especially statistics with graphs and charts is a golden rule. This helps to not only explain a particular topic but also reinforces the concept, which creates the “Aha!” moment for readers.
However, the use of visual cues should be done with utmost discretion because a blurry image, a badly designed chart or heaven forbid a completely irrelevant stock image will create more confusion than clarity.

Mistake 4# Churning out articles for every little topic

With help content, less is always more. What this means is that you don’t have to write a help article for every feature release or topic. Even if you feel it deserves a help article, always cross check with other teams to see if it actually deserves your time and effort.

At times, you may even need the help of data to understand whether the topic you are writing on is a relevant one. Once such resource is Google Analytics, where you can find pure gold in the form of “keywords” which give you a clear perspective on what exactly are the questions that customers are asking.

Technical writers should be precise and should write to the point content. It is important to avoid the above-mentioned mistakes for a crisp and clear writing tone. Keeping it simple and to the point would fulfill the most important purpose of authoring content, which is to put across information in the quickest and easiest way possible.

Share this article on

Do you want a free Knowledge Base Software?

We have the #1 Knowledge Base Software for delightful self-service help center starting at $0

About the author

Brayn Wills

Brayn is a knowledge management expert. He has been published in CustomerThink, PointVisible and Apruve. As a customer support specialist at ProProfs, Brayn has been instrumental in building a robust knowledge base and documents that help support executives keep every customer delighted. You can catch up with Brayn on Twitter and LinkedIn.


Leave a comment

Get Started Free