11 Most Common Mistakes in Technical Writing

The 11 most common technical writing mistakes we hope you don’t make, let’s go!

Poor Design/Layout

This is the first thing we are going to discuss and this is not by accident. Actually, the visual side of things is the first point of focus for your readers. You cannot undo the first impression.

You probably know this feeling, clicking a link that leads to a website that is supposed to be helpful but…it looks like it was made in the ’90s. Or even worse – the ’00s since ’90s are still kind of popular. Maybe screenshots are all over the place, maybe the font is unreadable, some content is displayed incorrectly…it can be anything and all these things combined that make a resource look untrustworthy.

Lack of Mobile Device Support

This is another thing connected to the first impression. Mobile devices are often overlooked by technical writers. Traditionally, most users would use PCs or laptops to open technical documentation. But times have changed. And being proactive in this matter will save you a lot of pain in the future when mobile traffic grows even more. For example, if you have a ClickHelp documentation portal, you can rest assured – your docs look OK on mobile and tablet devices.

Ignoring People With Disabilities

Modern technical documents need to be available to everyone. So, creating user manuals without having visually impaired people or people with dyslexia and other disabilities in mind is simply inappropriate nowadays. Full stop.

Poor Maintenance

Updating user manuals goes hand in hand with product releases. And maintaining technical documentation can be even more difficult than creating it from scratch. Because, well, you create it once, really, but maintenance…this goes on for as long as new product versions are being released.

It always shows when a doc team can’t keep up with their devs: a lot of new features are missing from documentation or there are some descriptions but they feel rushed. This and old screenshots are major red flags for readers that just scream ‘poor maintenance.’

Inconsistency

Inconsistency can be the result of poor maintenance, but not always. Sometimes inconsistency is caused by a lack of communication inside the team, where everyone is doing their own thing without discussing it or having one major resource to reference. Such a resource needs to be created and all the team members require access to it. This can be done in the form of a style guide, documentation plan, what have you. However you call it, it needs to be packed with guidelines and your team should take it seriously.

Mistargeting

Mistargeting can take different shapes and forms. If you are reading a help topic and it feels either oversimplified or like rocket science to you – you might be dealing with a case of severe mistargeting.

If your audience is too diverse, think about taking advantage of single-sourcing techniques and creating more than one version of your user manual covering each layer of your target audience.

No Feedback Channels

Technical writers get feedback mainly in the form of bug reports created by others. As a rule, the Support team writes a lot of these since they spend many hours searching through the docs.

Ideally, a technical writing team should have direct communication channels with clients. Achieving this is a no-brainer – add a comment section to help topics and allow users to rate them. ClickHelp allows all that as well as adding sharing buttons for social networks.

Lack of Structure

High-level documentation architecture is where it all begins and this is what is going to define the road ahead. This is a crucial stepping stone that requires a meticulous approach. If a mistake is made on the ‘basement’ level, the ‘house’ will start falling apart sooner or later.

Limited Team Collaboration

Technical writing is done by technical writers. By isolating your team from other participants of the product life cycle you will gain nothing. Continuous integration presupposes a continuous dialogue between teams. Otherwise, a lot of time will be wasted because of misunderstanding.

Not Enough Visual Content

As long as the product you are describing has a UI, there have to be screenshots. Video content is just perfect if you can make it short, informative and entertaining (to some extent). Don’t forget about graphs, schemes, tables and all that jazz. Walls of text are very unattractive and look lazy.

Stagnation

Unwillingness to evolve is always bad news. Understandably, it is hard to take a leap of faith with some brand new technology, approach or work process when you got everything figured out. But today’s world is very demanding especially when it comes to technology.

Providing zero documentation online is going to make you look like a dinosaur. Working with Microsoft Word as the primary technical writing tool and using emails for topic review will make you look if not like a dinosaur, then somewhat close.

Don’t be afraid to make a change when it is time to grow!

Conclusion

We believe that if you manage to avoid these mistakes, you will be on the right track to perfect user manuals! Be critical of your work. Revise and rethink, don’t stop, analyze the results and you should be fine.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices