If your developers, designers, admins, and staff members aren’t documenting their work, your business isn’t functioning as well as it can. Simply put, solid documentation efforts can really help improve the workflow and reliability of your processes. Not only does good documentation prevent a gap in understanding how something works, but it also makes it much easier for anyone to step into a role and be effective.
Thing is, however, bad documentation can actually be worse than no documentation. When documentation is written poorly, it can be a real struggle to use and can confuse staff members to the point where nothing can get done until that particular thread is unraveled.
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 given workflow
- General best practices
- Staff onboarding
- HR and staffing
Although documentation can take some time, the effort is worth it, as your company will save considerable time in the long run as well as avoid confusion and roadblocks down the road.
With that said, how can your developers improve their documentation? Let’s take a look at a few ideas.
Develop Documentation Policies
This should be the very first thing you do to improve documentation. It doesn’t matter if you’re just beginning this journey from the start 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’ll need to decide what is included with documentation, its intended audience, the preferred documentation tools, the role of comments, whether documentation will be housed in a version control system (such as Git), and if documentation is to adhere to a specific style guide.
Once you’ve developed 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 dramatically reduces clarity, consistency, and efficiency.
A simple example of active vs. passive voice looks like this:
- Active voice – Bob ran a marathon.
- Passive voice – A marathon was run by Bob.
When you use the active voice, the subject performs the action (Bob ran a marathon). When you use passive voice, the subject is acted upon (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 struggle for clarity.
Encourage the Use of Catchy Headings
Good documentation should be considered on the same level as writing any type of content. You want to use catchy headings so the reader knows exactly what follows and what to expect. This is especially true, given how everyone everywhere exists under an avalanche of content. Because of this, users tend to skim a lot more than they used to. When you use catchy headings (and subheadings) it makes the content much easier to read and take in.
Anything you can do to ease the burden on those having to depend on documentation should be considered a must.
Leave the Buzzwords and Acronyms Behind
When you adopt the use of catchy headings, make sure to avoid depending on buzzwords. This is especially important in technology because not everyone understands every buzzword and acronym.
When writing documentation, it’s important to approach it as if whoever is reading isn’t in the know and won’t be up on the current lingo. Documentation is there to help others understand how your company does and uses something. If your developers lean too heavily on buzzwords and acronyms, there’s no guarantee those reading the documents will comprehend what they’ve read.
Add Visuals
Whenever possible, add visuals to the documentation. This is especially important when you’re documenting how a GUI tool works. Instead of describing a graphical element, show a picture. After all, they say a picture is worth a thousand words, and, within the realm of documentation, that adage holds true.
Create and Use Templates
One thing you can do to make this whole process exponentially easier is to create documentation templates for your developers to use. This will drastically cut down on the work they have to do because they’ll have a simple document to guide them through the creation of their documentation.
When you create these templates, make sure you add to them any pieces of information that will not only ensure their documentation stays consistent but that make the final content easier to create. Consider this your means to hand-hold your developers through the documentation process. The easier you can make it for them, the more likely they will actually write the documentation and their work will follow your guidelines and be simple to use.
Conclusion
Crafting solid documentation should be placed 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 go smoother. Not only will your developers have an easier time creating documentation, but those who depend on the documentation also won’t have to struggle to decipher the meaning or intent of what they’re reading.
