Essential Tips for Effective Technical Documentation (Part 1)
Simple yet effective tips to level up your technical documentation
Hey everyone!
This is the first article of the series Essential Tips for Effective Technical Documentation. In this article series, I will share some key points I have learnt during the first few months as a Technical Writer.
As a technical writer, you should be able to provide accurate content in a much simpler way, so that the user understands it at first glance without further questions.
Whether you are a beginner technical writer or just wondering how to start tech writing, you can use these simple but effective tips to improve your writing skills.
📌 Tip #1: Identifying the audience
As the first step, understand your audience. Identifying the goal of your audience has a huge impact on the documentation process. In my opinion, it is the most important factor when it comes to writing technical documentation. It determines what to write and how to write the document. So, always keep the type of audience and their needs in mind when writing. Make sure you give the audience all the information that they need.
Often, you have to address two main audiences as a technical writer:
- Developers
- End users/ customers
Developers
Developers are the people who want to configure or maintain a codebase.
When addressing the developers, give instructions on how to configure or implement things. For example:
“You can include the profile selection step before the account selection step.”
Developers do not want step-by-step instructions on how to use a particular product or feature. But we can mention how the end users will use it, where necessary. For example:
“After the bank customers initiate a consent flow with an Accredited Data Recipient (ADR), they are redirected to the Data Holder’s authentication process.”
End users/ customers
End users or customers are people who want to use your product or application. Explain clearly how the product/application can help solve their problem with proper instructions. They simply do not care how it works.
When addressing the end users, mention how to use a certain feature, application, or product.
Understanding why your readers are referring to the documentation is necessary. Include only what is essential for them. For example, if you are addressing the end user you should not include the configurations behind the feature.
📌 Tip #2: Talking to the audience
If you are conveying instructions to the user, use the second-person point of view whenever possible. It means using the pronoun ‘you’ to speak to the audience. This has a conversational feel, and it implies that you are speaking directly to the reader.
Use the third-person narration only if needed. For example:
If you are addressing the developers:
- Use → “You can configure it as follows:”
- Instead of → “The developer can configure it as follows:”
If you are addressing the user:
- Use → “You can select your profile through …”
- Instead of → “The user can select…”
If you ignore this and mix things up, your audience will be confused.
📌 Tip #3: Being curious
Put yourself in the shoes of a reader. Always ask the questions, ‘why?’, ‘what?’, and ‘how?’. They might have so many questions. So, try to imagine what the user will ask next. Include all the possible answers so that the user is not confused.
Organize the content by looking from the reader’s perspective and ensure it addresses those questions. These questions also depend on the audience. For example:
If you’re writing for developers, view from a developer’s perspective and try to answer questions like the following:
- Why should I configure/ implement this feature?
- What will I need to configure/ implement this?
- How can I configure/ implement this?
If you’re writing for the end users of a system or application, view it from an end user’s perspective. Be curious like an end user who uses the system or the feature for the first time and try to answer questions like the following:
- Why should I use this system/ product/ application?
- What will I need to use this?
- How can I use this?
📌 Tip #4: Organizing appropriately
Organization is the key to successful technical documentation. It is how you organize the information and break it down into groups. First, understand the purpose of the document and the idea you want to convey about the particular product or application. Then convey the content to the reader by formatting it appropriately. Follow a logical flow within your documentation.
- Before going into details, provide a solid introduction to the feature. Include an overview, use cases, and suitable examples in your introduction.
- Provide an overview of the topics you cover in the article with a bulleted list at the beginning of the page so that the user knows what is included in the page. For example:
- Alternatively, you can arrange the table of contents in a side pane of the page. For example:
📌 Tip #5: Focussing on readability
Break long paragraphs into short sections and long sentences into short sentences. It increases clarity and readability. Long paragraphs and sentences make it difficult to grasp the content.
Tables
Include tables whenever you can summarize the information appropriately. It reduces the length and complexity and increases the readability of the documentation. It also provides a quick reference that helps readers locate information quickly.
Lists
Lists are useful for the reader for skimming. Lists also add whitespace to the document and make it easy to read.
- If a list does not follow a sequential order, use bulleted lists.
- For step-by-step procedures, use numbered lists to suggest a sequential flow.
Layout
Consider the layout and the visual effectiveness of the page too. Organize the important information using different styling. For example:
- Related information
- Important notes
- Additional tips
Make sure you use a consistent style across the document. Given below are some instances where we have used different styling to organize the content of the same type:
A proper layout helps the reader understand the information well and notice important content.
Bottom Line
The goal of a technical writer is to convey fully-tested, accurate information in a simple format. Ultimately, the document should help the reader to understand the product or process concisely. So, make sure you look at things from the readers’ perspective and structure the content in a well-organized manner.
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. In my upcoming blog posts, I will share a few more tips on how you can improve your technical writing skills.
Thanks for reading!
References:
Here are some great resources on technical writing:
