Essential Tips for Effective Technical Documentation (Part 3)
Simple yet effective tips to level up your technical documentation
Hey everyone!
This is the last article in the series ‘Essential Tips to Effective Technical Documentation’.
I already shared twelve key points in my first and second articles. In this article too, I will share another few tips that will help to create effective technical documentation.
Let’s get started!
📌 TIP #13: Using active voice
Passive voice is preferred in certain technical documents, such as reports. But when it comes to other technical documentation such as user documentation, writing in the active voice is the preferred approach. Using active voice makes the documentation clear and readable.
Avoid:
❌ “The profile selection can be done using one of the following 3 methods:..”
Use:
✔️ “You can select the profile using one of the following 3 methods:..”
Avoid:
❌ “The consumer is given a CDR receipt…”
Use:
✔️ “The consumers receive a CDR receipt…”
Using active voice makes the writing clear, concise, and more direct. When using active voice, it is important to know the doer of the action.
On the other hand, we use the passive voice when the action is more important than the doer. We also use passive voice when the doer of the particular action is unknown.
TIP #14: Writing in plain English
Use simple language. User documentation is not academic writing. Make the phrases as straightforward as possible. Go straight to the point without presenting too much unnecessary or repetitive information.
If a document is concise, it means that the document can convey its complete idea using the fewest words possible without damaging its clarity. For that, you have to eliminate the wordy sentences. Make the document less verbose.
Sentence length
Long, complex sentences are difficult to read and understand. They often confuse the readers too. Make the sentences as short as possible without damaging their meaning.
Using technical terms and abbreviations
When using technical terms or jargon in a document, make sure to provide a brief explanation of the particular term the first time it is introduced. Similarly, when using an abbreviation, make sure to mention its expanded version the first time it is used. Avoid unnecessary jargon. Avoid slang.
TIP #15: Avoiding “hiccups”
A hiccup is an issue that causes slowdowns or interruptions of something.
As we already discussed, technical documentation should always help the reader understand the content at first glance. There should be no distractions or fancy language.
If the readers feel a bit lost in the middle of a sentence, they are having a mental hiccup. It implies that the sentence needs to be rewritten.
To avoid hiccups we can,
- make the content concise and clear
- write in plain English
- write directly
TIP #16: Proofreading
Proofread the document before publishing it.
Also, it is necessary to run the document through a spellchecker such as Grammarly to fix language errors. Some spellings also differ from country to country. So keep in mind the audience you are writing for.
It is recommended to keep the doc aside for a few minutes before proofreading. The idea behind this is to have a short break or distract the mind with some other thoughts. Otherwise, our brain tends to read the same thing without noticing the mistakes.
TIP #17: Reviewing the documentation
You can carry out reviews such as self-reviews, peer reviews, or subject-matter expert reviews.
Review the content in terms of the instruction flow, clarity, language, and accuracy. Get the help of the developer from the product team to review the procedures and ensure you documented the instructions correctly.
Get a reviewer to test the instruction flow you’ve documented. Getting feedback from a reviewer is crucial for an effective document. Maybe you might have missed some points. A reviewer can help you with finding the missing or unclear instructions.
There are several types of reviews for technical documentation.
- Technical review: Usually, the product team or the subject matter expert (SME) does the technical review. They review the procedures, technical details, technical practices, and completeness of the document.
- Linguistic review: This is the step where you review whether the content follows the style guidelines. Here we mainly focus on the language, style guidelines, and technical writing best practices.
- Usability review: This is the step where you analyze if the documentation is easy to follow for the reader. Apart from the ease of use, you also consider effectiveness, efficiency, and user satisfaction. With a usability review, you cover the technical writing and UX aspects.
TIP #18: Getting feedback from a mentor
While it’s important to get feedback from the readers, it’s always important to get feedback from a mentor too. Getting feedback from a mentor helps you a lot especially if you’re starting your career as a technical writer. Always check with your mentors to find out what areas they think you need improvement in. Start working on improving those areas. Also, be open to both positive and negative feedback. Feedback is important whether it’s positive or negative. Constructive feedback is much more important because it teaches you how to improve the content as well as your skills.
Bottom Line
It’s time to conclude the series. I have been sharing some of the key points I have learnt during the first few months as a Technical Writer. These tips include some best practices we follow at WSO2 as Technical Writers and a few improvement points from the feedback I received from my mentor and lead.
I hope these simple steps will help you level up your technical documentation. Last but not least, apply these suggestions and practice as much as you can. Whether you are a beginner technical writer or just wondering how to enter into tech writing, you can use these simple but effective tips to improve your writing skills.
Thanks for reading!
