DEV Community

Cover image for How to Improve Existing Documentation.
Dule Martins
Dule Martins

Posted on • Updated on

How to Improve Existing Documentation.

I have been working on some sets of documentation for weeks now, and the task was to improve the documentation structure. align the documentation to fit specific style guides and establish clearer and more concise documentation.

With this, I produce content with consistent capitalization, spelling, punctuation, formatting, and grammar conventions. Also, I was able to control other writing variables, like tone of voice, and sentence fluency.

Improving existing documentation is an important step toward improving any written material's clarity, correctness, and usability. Here are some ways to improve your documentation:

Understand and review the existing documentation.

Begin by correctly reading and understanding the existing documentation. Determine its strengths, flaws, and places for growth. While doing that, you need to have at the back of your mind that there is a standard you expect the documentation to adhere to.

This standard is been measured by any style guide of your choice or organizational choice, within the context of my work I was using the Google developer style guide to establish a set of rules for subsequent documentation to follow.

Choose a Style Guide

Imagine owning a restaurant, and you want to maintain consistency in the test of food, creating this unique identity for your food leaves a lasting impression on your customers. You have something like a standard that all your chefs both past, present, and future chefs you work with, should follow. More like saying this is how we do things.

A style guide is a set of rules established to help technical writers work cohesively that reflects true corporate style and maintains documentation consistency. There are tons of style guide out there, you can choose to create one or adopt the existing one while you wait.

Set clear goals

Determine the purpose and goals of your documentation. What information should it provide? What problems or questions should it address? Having clear goals help you focus your efforts on relevant improvements.

Knowing what and where to implement your changes is the reason why you started with this task. My goals were to make sure the document followed the standard of Google developer's style guide, so I made sure my words and sentence structure were in line with that of the style guide.

I had to study the style guide, check for accurate use of words, linking text, and file extension format as well. My ability to understand the style guide was one thing that helped me produce the proper documentation.

Gather user feedback

Surveys are a great way to gather feedback from a large number of users. You can create a survey or integrate tools into your documentation so users can submit their responses online.
Once you have gathered user feedback, you can use it for continuous documentation. You can use the feedback to identify areas where your product’s documentation can be improved, and this feedback makes changes that make your product’s documentation user-friendly.

Summary

It is also important to make sure that the documentation is up-to-date and reflects the latest changes to the product.

Top comments (2)

Collapse
 
victoria_johnson profile image
VICTORIA JOHNSON

Love this!
Thank you for sharing.

Collapse
 
dule_martins profile image
Dule Martins

Thank you for loving it!