Having technical expertise is one thing, but being able to share it with others is another.
To present your product in the best light possible, you have to adjust your writing style and make the information comprehensible.
Unfortunately, many tech companies unwittingly jeopardize the success of their products by committing some common mistakes in technical writing.
In this article, you’ll learn about the mistakes that lower the quality of technical documentation and find ways to overcome them.
Once you start creating truly reader-centric technical documentation, your product and the company will stand a much better chance of retaining clients and customers.
So, let’s see how you can upgrade your technical writing practices.
Including Too Much Information
If you want to retain the reader’s attention, your technical documentation should cover only the most relevant information.
Including additional details might seem like a good idea because you want to paint the full picture of the product.
However, this reduces the readability of the documentation.
Research conducted by Accenture shows that excessive data overload not only leads to feelings of overwhelm, but also negatively affects the productivity of those who have to read the documentation too dense with details.
What is more, it brings about financial losses as well.
For instance, the yearly cost of data overload to the US economy exceeds $100 billion. So how do you avoid it?
Source: Accenture
You can decide on the right amount of information in technical documents by analyzing their aim.
The purpose of technical documentation isn’t to show your extensive knowledge about the subject; it’s to provide readers with the information about operating your product or solution.
Therefore, you should focus on making it informative and actionable.
Let’s take a look at the example of Datree’s documentation about CLI arguments.
The documentation was built with Archbee, our product documentation management software.
Source: Datree
As you can see, the author didn’t go into detail about why CLI arguments are used.
Instead, they offered a concise overview of the flags a user may get when using the Datree solution, together with their values and descriptions.
So, not a single sentence was wasted on insignificant details.
That way, the users get the relevant information, and they can move on to the next section without feeling overwhelmed with trivial details.
Since a knowledgeable author may find limiting the scope of information challenging, it’s a good idea to ask more people to review the documents before publishing.
They’ll be able to see objectively if there are any pieces of information that don’t contribute to the overall value of the documentation.
Having Too Many Inconsistencies
Inconsistent writing can confuse readers and ruin otherwise well-constructed documentation.
To avoid this technical writing mistake, you should draft a style guide and instruct each contributor to follow the prescribed rules.
While technical documentation focuses on products, it should be written with readers in mind because they are the ones who have to understand the product.
Consistency in writing is your greatest weapon here.
For instance, if you call a part of your software a feature, make sure you continue referring to it as such throughout the document.
That means that you shouldn’t use the terms such as feature, tool, and functionality interchangeably.
Unfortunately, many companies struggle with maintaining consistency in writing.
We’ve compiled a table with frequent offenders you should look out for.
Documentation created by multiple contributors is especially susceptible to inconsistencies.
A quick fix would be to ask each contributor to browse the existing documentation before writing new text.
However, a much more reliable practice is to create an internal style guide and keep it accessible in your knowledge base.
That way, all contributors will have a clear overview of good writing practices.
For instance, the style guide for authors at raywenderlich.com, publicly available on GitHub, clearly defines the language and vocabulary to be used.
One of the examples of how the guide ensures consistency is by listing preferred vocabulary.
For instance, authors are encouraged to use the word app over application, abbreviate “Frames Per Second” as FPS, not fps, and so on.
To get the most polished, reader-friendly version of technical documentation, you could go one step further and enroll frequent documentation contributors in a technical writing course.
Here’s one designed by Pluralsight.
Technical writing courses can give you insight into how to present software products in a readable way.
Combining that knowledge with your internal style guidelines will allow you to maintain consistency and provide the reader with documentation that is easy to follow.
Overusing Industry Jargon
Although jargon helps experts communicate with precision, your technical documentation should be approachable to clients and users of all backgrounds.
Because of this, you should avoid overusing jargon.
We’re not saying you have to resort to using plain language only because then you’d need more time and words to convey your ideas.
Instead, you should ensure that all your technical terms come with explanations.
You can do this by providing a definition when you first mention the word, or by creating a glossary.
The image below shows the glossary of technical terms used in Apigee, an API management platform.
As we wrote in our article about legacy knowledge in software companies, you shouldn’t assume that people outside of your company understand all your terminology.
Even your new employees may have difficulties understanding internal acronyms and abbreviations that have become ingrained in your company language.
Your clients and end-users have even less context, so a glossary or a word index is especially helpful for clarifying jargon.
If acronyms frequently appear in your technical documentation, but you don’t find creating a glossary necessary, a good solution is to introduce the full term the first time the phrase appears.
You can find an example of introducing acronyms in the following section of the raywernderlich.com style guide we’ve mentioned earlier.
As the guide states, there’s no need to explain commonly used acronyms such as API. However, industry-specific or company-specific jargon should come with definitions or explanations.
If you aren’t sure whether a phrase warrants an explanation, you might want to try out hallway testing, a method originating from UX design.
Depending on the technical documentation audience, you could ask a random person or a coworker from a different department to give it a read.
They’ll be able to tell you impartially whether the language is understandable.
Not Being Specific Enough
Since technical documentation should be easy to navigate, you should always give headlines specific names and include context to everything you’re mentioning.
Nader Dabit, an author and a web and mobile developer, lists vague writing as the most common mistake in technical documentation.
Dabit explains that the mistake includes abstraction, the programming technique of hiding information from the user in order to reduce it to its essentials.
However, if somebody is reading your technical documentation, they are interested in how the product works under the hub, so you should provide the reader with specific information.
The second mistake Dabit mentions concerns the exclusion of context.
There’s no use in writing an isolated piece of information without clarifying its context. Similarly, vague information can’t help readers understand the product better.
For instance, the heading “General information” in technical documentation doesn’t reveal much to the reader about the section’s contents.
Therefore, it’s better to give all of the elements descriptive names.
Here’s how Segmind, an MLOps platform, named the sections of their technical documentation that was built with Archbee.
Clear and precise headlines such as Integrations and CLI let the reader know what each section covers.
If you want to include some information you can’t put under a bigger category, you could create the miscellaneous section.
However, you’d have to make sure you still assign the subcategories recognizable titles.
Another great example of the practice comes from Segmind.
All in all, users read your technical documentation to find specific information.
You can assist them by providing context to all elements you mention and assigning the information recognizable, specific titles.
Failing to Structure the Content Well
A poorly structured sequence of information is a technical documentation mistake you can rectify by planning the content before you start writing.
The purpose of technical documentation and supporting materials is to transfer knowledge.
However, listing crucial information without paying attention to the sequence won’t help the reader learn about your product.
To present your product in the best light, you should plan both what information to include and how to structure it.
For instance, TalkChief, a business phone system, starts its product wiki logically, with setup instructions as the first element.
Readers are then presented with the choice between a mobile and a desktop setup.
The TalkChief wiki was also built with Archbee.
Our system makes it easy to create links between pages so that the readers can navigate the documentation effortlessly.
Here’s how TalkChief utilizes the feature.
In the Members section, the readers can click the word role, which is linked to the section that explains the three types of roles: agent, admin, and supervisor.
That way, readers can find more relevant information without searching the wiki manually.
When creating technical documentation, you should also keep your readership in mind, regardless of the subject.
Therefore, you should structure the information you’re presenting in a logical and digestible manner.
Take a look at the following example of instructions from the Dozuki technical writing handbook.
“Assemble small 90° adapter fitting to outlet port of filter base and orient so that free end of fitting will point toward backhoe and angled about 30° upward from horizontal.”
While an average reader probably understands each of these words individually, instructions formulated like this make comprehension difficult.
A better approach here would be to break the sentence down into three understandable chunks, as Dozuki suggests:
- Attach the small 90° adapter fitting to the port of the filter base.
- The free end of the fitting should point toward the backhoe.
- Angle the fitting about 30° upward of horizontal.
So, whether you’re writing technical documentation about a physical or a software product, you should strive to organize the information coherently.
This means taking care of the document structure, as well as the structure of individual pieces of information.
Neglecting to Include Enough Visual Content
If the product you’re writing about has a user interface, you should incorporate visual elements into the technical documentation to get your point across more accurately.
Visual content communicates more information in fewer words and helps the audience retain information.
It also shows you’ve put in the effort to make your documentation as easy to read as possible, instead of forcing your users to slog through a wall of text.
The most straightforward to make the documentation look more appealing is with images and screenshots.
For this section, we’ll use examples from Nexweave’s technical documentation, built entirely with Archbee.
Nexweave, a tool for creating personalized images, supplements its documentation with numerous screenshots demonstrating how clients can use the product.
To walk the reader through the product, Nexweave also uses GIFs.
GIFs require less effort to create than videos and can explain ideas better than static images, making them an ideal visual content type for demonstrating how features are used.
The GIF below shows the process of creating a bot on Landbot to be used with Nexweave personalized images.
If you want to describe a process in more detail, you could consider filming a video.
A great format for demonstrating digital products are screen recordings with voiceovers.
Most viewers prefer instructional videos ranging from three to six minutes, so make sure you keep the information concise and the videos engaging.
Here’s another great example of visual content from Nexweave.
Source: Nexweave on Youtube
Lastly, don’t forget that you can also use visual elements such as graphs, schemes, and diagrams to illustrate the information.
A good tool for building technical documentation will allow you to import diagrams created with external tools.
For instance, Archbee integrates with Mermaid, a diagramming and charting tool.
The integration enables you to visualize data effortlessly and boost the quality of your technical documentation.
Conclusion
No matter how complex your product is, there are still ways you can make it graspable.
Remember, the way you tell the story matters as much as the contents of technical documentation.
The reader should be able to navigate the documentation with ease, and there should also be plenty of visual content to make the information clearer.
However, writing and shaping technical documentation doesn’t have to be a chore.
Archbee, our product documentation platform, will help you shape it into an engaging format, ensuring that your clients always find the information they need in seconds.
