Your company's documentation is probably lacking in many ways, but with just a little work and guidance, your developers can take it to the next level.
If your developers, designers, administrators, and team members don't document their work, your business isn't running as well as it could. Simply put, solid documentation efforts can really help improve the workflow and reliability of your processes. Good documentation not only avoids gaps in understanding how something works, but it also makes it much easier for anyone to step into a role and be effective.
The problem is that bad documentation can be worse than no documentation. When documentation is poorly written, it can be difficult to use and can confuse team members to the point where nothing can be done until that specific topic is figured out.
And documentation doesn't just apply to developers. Documentation can be used for anything within your company, such as:
- How to use software
- How to use hardware
- Any workflow
- General best practices
- Team integration
- HR and personnel
Although documentation may take some time, the effort is worth it as it will save your business considerable time in the long run, as well as avoid confusion and obstacles in the future.
That said, how can your developers improve your documentation? Let's take a look at some ideas.
Develop documentation policies
This should be the first thing you do to improve documentation. Whether you're just starting this journey from scratch or are taking on the task of improving all of your existing documentation: take the time to develop policies for the process and the end results.
For these policies, you will need to decide what is included in the documentation, its intended audience, preferred documentation tools, the function of comments, whether the documentation will be hosted in a version control system (such as Git), and whether the documentation will adhere to a specific style guide.
Once you develop these policies, make sure all documentation follows them to the letter.
Use active voice
In the name of creating succinct, easy-to-follow documentation, your developers need to understand how to use active voice. The opposite of active voice is passive voice and it drastically reduces clarity, consistency and efficiency.
A simple example of active versus passive voice goes like this:
- Active voice – Bob ran a marathon.
- Passive voice – A marathon was run by Bob.
When using the active voice, the subject performs the action (Bob ran a marathon). When you use the passive voice, the subject suffers action (a marathon was run by Bob).
You want every sentence in your documentation to be as clear and simple as possible. Don't complicate things and don't make the reader of the documentation have to work for clarity.
Encourage the use of catchy titles
Good documentation should be considered on the same level as writing any type of content. You want to use catchy titles so the reader knows exactly what's next and what to expect. This is especially true considering how everyone, everywhere lives under an avalanche of content. Because of this, users tend to skim a lot more than before. When you use attractive titles (and subtitles), content becomes much easier to read and absorb.
Anything you can do to ease the burden on those who rely on documentation should be considered mandatory.
Leave the buzzwords and acronyms behind
When embracing the use of catchy titles, avoid relying on buzzwords. This is especially important in technology because not everyone understands all the buzzwords and acronyms.
When writing documentation, it is important to approach it as if whoever is reading it is not in the know and is not familiar with the current language. Documentation exists to help other people understand how your company does and uses something. If your developers rely too heavily on buzzwords and acronyms, there is no guarantee that those who read the documents will understand what they read.
Add visuals
Whenever possible, add visuals to documentation. This is especially important when you document how a GUI tool works. Instead of describing a graphic, show an image. After all, they say that a picture is worth a thousand words and, in the scope of documentation, this saying is true.
Create and use templates
One thing you can do to make this entire process exponentially easier is to create documentation templates for your developers to use. This will drastically reduce the work they will have to do because they will have a simple document to guide them in creating their documentation.
When creating these templates, be sure to add any information to them that will not only ensure your documentation remains consistent, but will make the final content easier to create. Consider this your way of guiding your developers through the documentation process. The easier you make it for them, the more likely they are to actually write the documentation and their work will follow your guidelines and be simple to use.
Conclusion
Creating solid documentation should be at or near the top of your list of things that are important to the efficiency of your company. With a solid documentation process in place, everything will run more smoothly. Not only will your developers have an easier time creating documentation, but those who rely on documentation also won't have to struggle to decipher the meaning or intent of what they're reading.
