Creating Effective Documentation Is Easy

Gone are the days when user manuals were voluminous texts used as paperweights or door stoppers. The days where documentation was more of a formality, created during product development and left gathering dust without so much as a minor update, are (thankfully) behind us.

I have worked on several such projects where the documentation was passed directly to the customer without so much as a cursory review.

What is effective documentation?

In a nutshell, effective documentation is one that addresses the reader’s need with a minimum word count. It elaborates only when necessary, states the facts directly, and doesn’t beat about the bush. Effective documentation is important to improve readability.

You will have the full picture by the time you finish reading this article.

Do we need effective documentation in technical writing?

Documentation plays a pivotal role in a product’s success. I have sat through several meetings with prospective clients where they cited documentation as one of their reasons for picking the product for their business requirements.

Users today just do not have the time or patience to read through the entire mythos of the product, the company, etc. Readers want documentation to be tailored to their requirements and the content to address the topics for which they refer or need the documentation.

Therefore, it is your responsibility as the content creator, or technical writer to create such content. Effective documentation can boost your content with improved readability.

Can you identify effective documentation?

Yes, you can! You can identify effective documentation based on two factors:

• Readability: How easy it is to read and understand the document.
• Usability: How easy it is to use the information in the document.

If you can make an honest assessment of your content and rate its readability and usability, you can gauge the effectiveness of your documentation.

What are the qualities of effective documentation?

Effective documentation can be identified based on certain qualities. The ability to imbibe your content with these qualities is what qualifies you to be a technical writer. Otherwise, any developer or SME can create documentation and organizations won’t even need a specialist.

The content in an effective documentation has the following qualities:

• Audience-centric
• Modularity
• Conciseness

Audience-centric

Your content must be audience-centric, i.e. tailored to the audience. The significance of audience analysis or understanding the audience has been stated in my Essential skills for a technical writer article already.

The better you understand the audience, the better you understand what they need from the document. Using this understanding, you can filter the unnecessary stuff out and turn your content and turn it into an effective document.

In my experience, there are the following broad categories of audience. Each category uses documentation differently.

• Business heads and stakeholders such as CEOs and CTOs come to the documentation primarily to check out the product or topic’s usability. They are trying to understand if the product solves their problem.
• Citizen developers, users without in-depth knowledge of the technology but typically functional SMEs in the domain, want to look at procedures for specific tasks and troubleshooting items.
• Developers, users tasked by citizen developers and stakeholders to use the product, want to get a deeper understanding of the product to be able to install, configure, and use the product.

Modularity

Modularity is also an essential aspect of the software development lifecycle (SDLC), modular code is easier to read, update, and troubleshoot. Likewise, in DDLC too, modularity plays a big role in improving user experience.

Modularity is where the content is divided into bite-sized chunks. Modular content does not overburden the reader with information. Keeping in mind the wide spectrum of readers, the information is split into digestible chunks. You cover the primary aspects of the topic in the main body and add sub-sections tackling the secondary aspects. In doing so, you do not force the reader to look through the entire haystack to find their needle.

Readers curious about the entire topic have to freedom to browse through the sub-sections.

Such directed documentation can be created using two aspects, structuring the content well, and keeping the content concise and tight. This article covers the latter.

It is important to understand when someone reads the documentation. If you can understand what makes a user open the documentation, half your battle is already won.

Conciseness

Conciseness has a huge impact on the document’s readability. No content, no matter how useful, informative, or filled with illustrations is readable if it goes on and on without an end in sight. Conciseness is so important that even video content is designed to last only as long as the typical viewer’s retention. I also try and keep my content concise as much as possible by keeping the word count under 1500 words (or a 9-minute reading time, at most). Remember, conciseness improves readability.

That’s not to say that the content cannot be longer than that. The content must be only as long as justified by the topic. If you are documenting a procedure, document only the procedure. If you are discussing a product, keep it focused on the product alone.

Effective documentation practice exercise

Let’s look at a sample procedure to understand how all three qualities improve the effectiveness of the content.

1. Download and extract the APK from the website.
2. Log into GitHub.
3. Go to the project’s repository in GitHub to download the configuration files.
4. Select the required branch.
5. Click the Clone button to clone the repository.
6. When prompted, select a target folder for the repository. This downloads the repository as a compressed ZIP file in the specified location.
7. Navigate to the folder where you cloned the repository.
8. Extract the repository’s ZIP file.
9. Copy the file from the APK Configuration folder into the APK’s file.
10. Open the Terminal and run the following command to build the APK.
    npm build
11. Start the HTTPS server with the following command:
    npm start https

Now, take a look at the following procedure:

1. Download and extract the APK from the website.
2. Clone the project’s repository on GitHub to download the configuration files. For detailed steps about cloning a GitHub repository, see the Cloning GitHub Repository section.
3. Unzip the cloned file and then copy the file from the APK Configuration folder into the APK’s file.
4. Open a Terminal window and run the following command to build the APK.
   npm build
5. Start the HTTPS server with the following command:
   npm start https

Do you see the difference between the procedures?

The first procedure assumes that the reader is not aware of cloning GitHub repositories and thus goes into a tangent explaining it in the main procedure itself. It also has several steps that can either be removed or combined into one. For example, step #2 is unnecessary when you have step #3.

Any user reading the procedure has to go through all the steps and replicate them in their machines. Even if the user knows how to clone a repository in GitHub, they are forced to read through the GitHub-related steps. Add screenshots at each step, and the procedure alone occupies considerable space, introducing several more scrolls.

Each second the reader spends scrolling through unnecessary content, the user experience drops a degree!

However, the second procedure keeps the steps to clone a GitHub repository in a separate section (modularity). This helps an experienced reader focus only on the main procedure while also enabling an inexperienced reader to know the procedure to clone a GitHub repository when they refer to the corresponding section (tailored for the audience). And lastly, the second procedure eliminates redundant or unnecessary steps (conciseness).

How to write effectively?

As a technical writer, it is very easy to improve the effectiveness of your existing content, create new effective content, and inculcate the skill to write effectively. Here is a brief guideline that I follow when creating content.

Any product documentation can have two types of content:

• Paragraph content. Descriptions, definitions, concepts, bullet lists, etc.
• Procedures. Step-by-step instructions.

You tackle each type differently to make the content more effective.

Effective documentation in paragraph content (concept or reference topics in DITA)

1. Sort the content based on its essentiality to the typical reader. Must have, good to have, and unnecessary.
2. Chuck the unnecessary content out. If the reader will not miss it, it is just dead weight, literally! Most organizations host documentation on web servers, so the lighter the documentation, the cheaper it is to maintain.
3. Nestle the good to have content into sub-sections or child nodes, link to it from the main content, so a reader goes to it only when necessary.
4. Retain the must-have content in the main body of the documentation.

Effective documentation in procedures (task topics in DITA)

1. Break up complicated procedures into smaller sub-procedures when possible.
2. Simplify complicated procedures with screenshots and videos.

Conclusion

• Effective documentation in technical writing understands the user or reader well and addresses their need directly.
• Users and readers do not want bulky content.
• You can identify effective documentation based on its readability and usability.
• Effective documentation has three qualities: tailored to the reader, modularity, and conciseness.
• To improve a document’s effectiveness:
  • Trim the unnecessary content.
  • Retain primary content in the main body.
  • Keep secondary content in a sub-section and link to the main body.
  • Split complex procedures into sub-procedures.
  • Keep additional procedures or extra procedures in a separate section.

Here’s an article talking about writing concisely to achieve effective documentation.

I hope you found this article helpful. If you didn’t, then I would love to hear from you about what I can do to improve it. For more technical writing-related articles and resources, see the Technical Writing page. Also consider following my YouTube channel learntechnicalwriting, Reddit community r/learntechnicalwriting, and Quora space Technical Writer | Technical Writing for more such content.

Affiliate disclaimer: Some of the links in this article are affiliate links. This means that I can get a little commission if you subscribe or make purchases using the link at no extra cost to you.