Essential Tips for Effective Technical Documentation (Part 2)

Simple yet effective tips to level up your technical documentation

Image Source: Pexels

Hey everyone!

This is the second article of the series Essential Tips to Effective Technical Documentation. In this article series, I am sharing some of the key points I have learnt during the first few months as a Technical Writer.

Providing accurate content in an easily digestible way is a technical writer’s key responsibility. So that the user understands it at first glance with no further questions.

I already shared five key points in my first article. Today I will share another few tips that will help to create effective technical documentation.

Let’s dive in!

📌 TIP #6: Using Meaningful Titles

The title plays a major role in any type of content.

Using relevant titles

The title of your technical document should be:

• relevant to the topic
• properly defined
• able to clearly emphasize the purpose of the document
• properly summarized

We already know that the purpose of any kind of technical documentation is to provide technical knowledge to the readers. To be an effective document, the title should specifically describe the topic you want to write about. Therefore, the title should always be specific. For that, you have to understand the purpose of your document and compose the titles accordingly.

For example, you want to provide information to your readers on:

• customizing your product/ solution
• buying your product or service
• your latest products
• how to use your application

Writing for skimming

Include titles in a way that the reader can skim the content easily.

For example, the content on the below page is organized effectively so the reader can grasp the content at first glance.

Sample Page Structure | Image Source: WSO2 Open Banking Documentation

Notice the following in the above example:

• Titles, tables, lists, and other styles are organized to emphasise the important points.
• Headings and subheadings are kept in the same format.
• A consistent font type and font size are used throughout the document.

📌 TIP #7: Using Graphics

Using visuals plays an essential role too. Usually, technical documents contain the following:

• Diagrams
• Flowcharts
• Graphs
• Infographics
• Screenshots

Graphics communicate ideas better than words. They reduce the complexity of the documentation and increase clarity. Draw.io is an easy way to create such infographics.

Additional Tips:

• Follow the guidelines and the branding of the company to maintain consistency throughout the pages.
• Add Alt tags to the graphics as it helps the people who are visually impaired. (Alt tag refers to the alternative text for a particular image. It is useful when the image is not loaded or the users use a screen reader.)

📌 TIP #8: Never Assuming Things

The developers in the product team already know everything related to the product or feature that you are documenting. So they usually tend to assume the readers also have similar knowledge and capacity which they do not, most of the time. Therefore, as a tech writer, you should write the documentation more simply so that a person with basic knowledge can read and understand the instructions.

Write clear, step-by-step instructions in plain English. Place yourself in the shoes of a first-time end user of the system or product. Do not assume they understand the things you already know. Sometimes they cannot figure out the instructions you have missed. Your readers should get the information as quickly as possible.

Additional Tip:

The first time you mention a new abbreviation, describe what it stands for.

📌 TIP #9: Providing Examples

Examples are the best way to understand any concept effectively and quickly.

You can provide examples for various instances including the following:

• Referring to a real-world scenario: Sometimes it’s difficult to understand the complex things you describe at first glance. But it’s easier if you provide a real-world example that explains the use case behind the complex concept.
• Providing sample values: Another importance of providing examples is when explaining to set up or configure something. Provide actual values.
• Providing sample code snippets: When you write how to implement something, provide examples with code snippets.
• Including screenshots: If you document a step-by-step guideline, make sure you add suitable screenshots whenever possible.

📌 TIP #10: Testing the Documentation

After creating the draft, take time to follow the steps of the document that you just created. Start setting up things from scratch and try things out to test if the documented steps work.

Once you go through the steps, you might notice some missing, unclear, or wrong instructions. There might be gaps in the documentation in terms of completeness and accuracy. So make sure you pay attention to every small detail in the document and make it error-free.

📌 TIP #11: Following documentation guidelines

Documentation style guides contain the standards for the documentation process which usually include formatting, grammar, words, etc. They help you to clarify the doubts on technical documentation. Following the standard guidelines lead you towards consistency. It increases the readability of the reader.

Here are some editorial style guides for technical writing:

• Google developer documentation style guide — Includes editorial guidelines for writing Google-related developer documentation
• Microsoft Writing Style Guide — Includes guidelines for writing technical documentation
• GitLab Documentation Style Guide — Includes editorial guidelines for writing GitLab documentation

📌 TIP #12: Avoiding bias/ using gender-neutral terms

Using gender-specific pronouns is highly discouraged when writing a document for a wide audience. Sexist language can exclude a certain portion of the readers. Therefore, avoid using gender-specific pronouns and words such as ‘he’ or ‘she’. Use words like ‘they’ or ‘you’ instead. For example:

Avoid:

❌ Once the customer selects the relevant profile from the Profile page, he is redirected to the Accounts Selection page.

Use:

✔️ Once you select the relevant profile from the Profile page, you are redirected to the Accounts Selection page. (in a user document)

✔️ Once the customers select the relevant profile from the Profile page, they are redirected to the Accounts Selection page. (in any other document)

Using gender-neutral language shows you are respecting everyone and avoids confusion among the readers.

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 reader’s 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.

Let’s meet soon with the last article of this series! Until then, stay safe!

Thanks for reading!