Most of us would rather be thrown in the scorpion pit than be asked to write a manual, despite the fact that this would be the best way of showing off the brilliance of the program we wrote to a wider audience.— David Clayworth, Fog Creek Software
Much like the writers that hate editing, many software developers delight in writing code but loathe the part where they have to document what they have just done. Clayworth theorizes that the avoidance of documentation comes from a belief that developers like to work in ideas, and once those ideas are set, there is no interest in communicating them. Other reasons might have to do with time or manpower constraints on a project or feeling that it’s tedious and a waste of time.
But complete and concise software documentation is essential for those who come next — whether it’s the young programmer that will visit your code in the future, a teammate or to a wider audience that wants to adopt it.
While we’ve already covering how to write documentation, let’s explore some of the ways developers can get motivated to create better software documentation.
Keep Track of How You’re Doing
A good way to get a sense of how well you’ve been doing documentation is to go back and read some of the documentation you’ve written (hopefully you’ve gotten around to writing at least some documentation).
“The most effective way I’ve found to increase the quality of my documentation is to look up a random block of code I wrote more than six months previously, and see if I can describe to myself what the block’s inputs, output, functions and limitations are within five minutes,” said Bill Horne, moderator of The Telecom Digest. “If not, then I know I’ve got to up my game.”
Try it out, find some old code and see if you can figure out how you did it solely from your documentation. If you’re having trouble, read on to find ways to improve.
Check Out the Documentation Standards and Then Practice
Maybe you don’t know where to start with documentation or were never taught properly. A good starting point or place to refresh your documentation skills can be found by checking out the IEEE standards. Jon M. Quigley, founder of Value Transformation LLC, recommends starting with these standards:
- IEEE Std. 1233-1998 IEEE Guide for Developing Systems Requirements
- IEEE Std. 830-1998 IEEE Recommended Practice for Software Requirements Specifications
- IEEE Std. 1016-1998 IEEE Recommended Practice for Software Design Descriptions
After checking those out, Quigley recommends getting to know them, “The way to get better, like so many things, is to study, practice and collaborate.”
With practice, documentation can become second nature.
Become a Better DevOps Pro
Gamify the Documentation Process
Why gamification has been such a successful concept is because people enjoy doing a task they get rewarded for. From a biological level, pleasant experiences release the feel-good chemical, dopamine, in our brains. When something feels good, we are more likely to do it again to get that burst of pleasure.
John Chapin of Capital Technology Services, recommends finding a tool that can be rewarding and improve documentation.
“One of the best ways to reinforce writing documentation is if you have code style tools that specifically highlight the lack of documentation AND you connect these to a chart in your continuous integration environment,” said Chapin.
“It’s a matter of setting up a feedback loop where developers know that documentation/quality of the code is something we’re measuring. If developers know that the chart is going to tick upward because they’ve left classes or functions undocumented, then they’re going to document their work.”
You can learn more about gamification and documentation here.
Use Fiction Writing to Improve Documentation
Envision writing code like authors write fiction. Thursday Bram, of ThursdayBram.com, finds that the rules that authors follow to write some of the most successful fiction pieces also work well for writing documentation that is helpful and successful.
“Writing can be an enjoyable process, whether you’re writing documentation or fiction,” said Bram. “Either way, you’re working on communicating a clear message to your readers, and the methods for doing so are surprisingly similar whether you’re spinning a tale or providing clear instructions.”
To accomplish this task, Bram created an updated list of Elmore Leonard’s 10 Rules of Writing to be software documentation-friendly:
- Never start a piece of documentation with a general description of your community or ecosystem.
- Better yet, avoid starting with anything that isn’t relevant to your documentation.
- Keep your verbs simple and actionable.
- Write clearly. Don’t use adverbs or other fancy parts of speech if you don’t need ‘em…
- Keep your exclamation points under control.
You can see the next five rules from Bram in her talk, What Writing Fiction Teaches You About Writing Documentation.
When It Comes to Software Documentation, Think About Others
Whether it’s the user or the programmer that will follow you, Harry E. Keller, Ph.D., President, Chief Science Officer, and Founder of Smart Science Education Inc. He recommends thinking of the person who will look at the code after you.
“As a software engineer, you should show consideration to the next person who will work on your code. It’s not perfect. It may have to be enhanced or upgraded,” said Keller. “Pity the person who comes next. By being that person, you will begin to understand exactly how important good documentation is. You may even figure out what makes good documentation good.”
What are your ideas for getting motivated to write better software documentation? Leave your tips and tricks in the comments below.
BECOME A DEVOPS PRO
FREE DEVOPS COURSE
- Docker Tips and Tricks
- Agile Methodologies
- Documentation and Tools Hacks
- Containerization vs Virtualization