When you’re writing technical documentation for a software product, the ultimate goal is to communicate the information clearly, concisely, and accurately.
With that in mind, new and experienced technical writers alike should avoid some common pitfalls that can make their documentation confusing, inaccurate, or outdated.
So, here are six mistakes that good technical writers avoid doing when creating high-quality documentation, with a special focus on software documentation.
Not Consulting With Subject Matter Experts
Simply put, not consulting with subject matter experts (SMEs) can result in software documentation that contains incorrect or outdated technical information or lacks important technical details.
It is worth noting that such documentation will be a source of many user frustrations and even more user support emails and calls, ultimately hurting the product’s reputation.
To avoid this, technical writers must get all the facts right and understand the software product they’re writing about, and SMEs can provide the necessary expertise to do so throughout the writing process.
In other words, if we assume that technical writing, in its simplified form, consists of five stages, shown below, then advice from the SMEs could be required in any of them.
If you’re a writer planning their new documentation writing assignment, you should ask SMEs about the best sources to familiarize yourself with the software product you’ll be writing about, its features, and its target audience.
Since the planning stage is often the first time you communicate with SMEs, this is also an excellent opportunity to establish a good working relationship with them, thus facilitating their input later in the writing process.
In addition, you should find out if any pre-existing documentation needs to be reviewed, and address any other questions you might have at this stage.
This will ensure that the second stage of your writing process—research—goes in the right direction, enabling you to gain a comprehensive and accurate understanding of the subject you’re writing about.
The process of familiarizing yourself with the software product will depend on your initial knowledge of the subject matter, but it can be accelerated by consulting with SMEs.
In the words of Rachel Bishop, technical writer at Huntress:
To speed up the process, I read and googled and researched—but I also reached out to the SMEs we had internally to bring me up to speed on what I needed to know.
Once you’ve written the documentation, the review/edit stage should incorporate feedback from SMEs and other stakeholders.
Overall, not consulting with SMEs at the right time—or at all—to verify the information and ask for clarification will result in inaccurate and incomplete documentation.
Assuming How Much the Audience Knows
Assuming instead of determining how much your target audience knows is a common mistake made by many technical writers.
Incorrect assumptions can lead to users being confused and frustrated, misunderstanding the documentation, and consequently, misusing the product itself.
In turn, this can cause lower software adoption, hurt the consumers’ trust in the product and the company making it, and result in your user support service being swamped with countless messages and calls.
Therefore, good technical writers will ensure they understand their target audience and tailor their writing to suit the audience’s knowledge, skills, and experience.
In other words, the documentation you’re writing for beginners in a particular field, such as junior developers, is going to differ from users with more advanced knowledge about the topic, such as senior developers.
So, before you start writing, you should interview SMEs and other people involved to find out answers to the following questions:
These questions—and all the follow-ups if the answers are not precise enough—will help you better understand your target audience, the average level of their technical knowledge and skills, and their specific needs and concerns.
As a result, you’ll be able to create user-friendly documentation that addresses those needs and anticipates potential issues like common errors or compatibility problems, maybe also in the form of a troubleshooting guide.
In other words, experienced technical writers will probe SMEs and other stakeholders to determine what the intended audience needs to know and ensure that such information is included in the documentation.
Overall, good technical writers avoid making assumptions about how much their target audience knows and invest time and effort to better understand their level of knowledge, as well as their specific needs and concerns, in order to create audience-friendly documentation.
Using a Lot of Technical Language
Although some technical language is unavoidable in software documentation, good technical writers refrain from using a lot of technical jargon and needlessly complex language that can make the documentation difficult to understand for the target audience.
In other words, it all starts with understanding your intended audience, as discussed in the previous section.
For example, if you’re writing for beginners in a field, such as junior developers, you will need to provide more detailed explanations of technical concepts than when writing for senior developers.
Likewise, when writing for a general audience or people specialized in other fields, you should never assume that a technical term or acronym doesn’t need to be explained just because you (and your professional community) are familiar with them.
For example, in the context of API (Application Programming Interface) documentation that typically contains a lot of specialized technical terms, Kin Lane says:
This quote can apply to all other types of software documentation.
Regardless of the type of software they are writing for, good writers should focus on writing in plain language, avoiding technical jargon whenever they can.
However, good writers also understand that technical language in software development can’t be avoided, so it’s best to:
- briefly define technical terms and acronyms when they first appear in the text
- organize them in a glossary
Naturally, this will benefit users, but it also allows writers to be more accurate and consistent in using specialized terminology.
To summarize, instead of technical jargon, technical writers should write in plain language tailored to the target audience and define technical terms and acronyms, to make sure their audience understands them perfectly.
Writing Sentences That Are Too Long
Besides avoiding too complex technical language, good technical writers try to avoid overly long sentences.
The reason is that such sentences progressively lose clarity, making them difficult for readers to follow.
To keep their sentences short and simple, writers can calculate the Gunning Fog Index for the software documentation they’re writing.
The Fog Index is a readability test devised by Robert Gunning in 1952 as a way to evaluate the complexity of written materials such as contracts and other legal documents, academic papers, and technical documentation.
Here’s the formula for calculating the Fog Index, courtesy of Readable:
The formula first takes the number of words in the text sample and divides it by the number of sentences to get the average sentence length.
Then, it counts the number of complex words per 100 words, adds that number to the average sentence length, and multiplies the resulting number by 0.4.
The obtained index score will estimate the years of formal education a reader needs to understand the text after reading it once.
In other words, the lower the score, the easier it is for users to comprehend what they’re reading.
Of course, this practical readability test from the 1950s can be done manually, but today there’s really no need. There are online tools which can do that in just a few clicks.
Generally speaking, technical documentation should score no higher than 17.
Still, different sources cite different index scores, so the desired Fog Index will ultimately depend on the subject’s complexity and the assessed level of the target audience’s technical expertise.
To improve the readability of documentation, technical writers should also strive to break down long paragraphs (e.g., by using bullet points) in addition to using shorter words and sentences.
In summary, to ensure clarity and simplicity in their writing, good technical writers keep their sentences on the shorter side whenever possible.
Rushing Through the Writing Process
Despite often facing tight deadlines, large workloads, and last-minute changes, good technical writers avoid rushing through the writing process.
They avoid cutting corners in the writing process when deadlines are approaching, as that can lead to errors, inaccuracies, and inconsistencies in their software documentation.
These shortcomings can then cause user frustration and adoption issues with the software.
Therefore, technical writers should follow the stages of the writing process, which usually involve research, consulting with SMEs, creating an outline, writing, editing, and proofreading the documentation.
So, let’s take a closer look at why technical writers can feel pressured to rush their writing:
As already mentioned, too much work and unrealistic deadlines lead the way, closely followed by unannounced changes just before the finish line.
Moreover, difficulties with SMEs can range from being late with responding to questions or reviewing the documentation to poorly communicating their subject matter knowledge or simply perceiving technical writers as not being worth their time.
Technical writer Geoff Hart lists some of the problems he found frustrating in his encounters with SMEs:
SMEs making undocumented changes in the interface or underlying algorithms, SMEs forgetting an agreement to keep me posted about such changes, and lazy or careless documentation reviews.
Naturally, all these issues can slow writers down at any stage of their writing process, causing delays and frustration and piling on the pressure to meet deadlines.
To speed up their writing process, technical writers should make good use of different tools, such as project management software, communication apps, and document management platforms.
Such tools can be of immense help when trying to streamline the writing process and identify and resolve issues early on.
For example, a documentation tool like Archbee combines everything technical writers need to create software documentation, track changes, and easily edit and update documents.
At the same time, Archbee allows them to regularly communicate, collaborate, and receive feedback from SMEs and all other relevant stakeholders, for instance, by making inline comments.
Such software tools can help writers keep track of deadlines, changes, and feedback while prioritizing communication to keep everyone on the same page, all of which can mitigate the issues that could force them to rush their writing.
Furthermore, writers should establish a schedule with some buffer time between stages of the writing process to address unexpected changes or issues.
In conclusion, when faced with a difficult situation, good technical writers do not rush but have tools and processes in place that help them ensure the documentation is accurate, complete, and updated—even under challenging circumstances.
Not Improving Published Technical Documentation
Last but not least, good technical writers know that publishing technical documentation doesn’t mean their job is over.
Simply put, just like the software it accompanies, technical documentation is a living record that changes over time, meaning it needs to be maintained and improved.
For starters, users can point out inaccuracies or ambiguities in technical documentation, which need to be corrected or clarified to improve the user experience.
This also means writers should keep track of how the documentation is performing and listen to feedback from the target audience to make improvements.
Furthermore, as new features and updates are released, the documentation also needs to be changed to ensure it stays accurate and relevant.
Other reasons for updating software documentation include security vulnerabilities, changes to industry standards and regulations, or changes in the target audience.
Therefore, to prevent the documentation from becoming misleading or outdated, technical writers should take measures to keep it up to date.
Here are five ways how writers can do that, courtesy of JetBrains.
Of course, close collaboration and open lines of communication with key stakeholders allow technical writers to stay in the loop about what’s going on with the software and, by extension, its documentation.
Naturally, knowing when changes occur can be crucial for the writer’s timely reaction, and they can use different tools, such as a task tracker, to automate the process and ensure they’re notified about changes.
As for improving published technical documentation to serve the software users better, regularly reviewing interactions between them and the support team (i.e., support tickets) can be extremely helpful in identifying areas where documentation can be improved.
Overall, good technical writers will never neglect the fact that technical documentation must be regularly updated and constantly improved to keep it accurate, complete, and user-friendly.
Conclusion
So, having covered six things good technical writers avoid doing, it’s clear there is a lot to consider before, during, and after writing documentation.
Before writing, technical writers should consult with SMEs and research the target audience.
When writing, they should avoid using excessive technical language and too long sentences or rushing through the writing process.
After writing, they should keep improving and updating the published technical documentation.
The end result?
High-quality documentation that builds trust, improves user satisfaction, and increases the success of the software product.
‍
