Writing documentation is not the most exciting endeavor an engineer can embark on. It’s often boring, time consuming, and there are so many more interesting things that could be done. It sometimes amazes me how poorly development projects are documented if they are even documented at all. Documentation is meant to help preserve important concepts and information about the development cycle. This information could be used to get up to speed on the product, make decisions about updates and changes or to even prove that proper procedures were followed to create the product. In today’s post, we are going to examine several tips for developing documentation that decreases the pain factor for developers and improves documentation quality.
Tip #1 – Write the documentation as you develop
The problem with a lot of documentation (which includes code comments), is that the documentation is done after the development is completed. Engineers are often in a hurry due to delivery constraints, so they focus on getting things working first and then document second. The problem with this is that there is a good chance that the documentation is never written and if it is, the developer may be writing it weeks or months later which means they have forgotten the design decisions that were made. The resultant documentation is often better than nothing, but lacking in critical steps or thought processes that make it easy to pick-up right where the developer left off.
I’ve found that the best documentation, and the quickest way to develop it, is to document as you go. For example, when I am writing documentation that describes how to setup and run a test, I don’t set it up and then go back and try to remember all the steps I took. I literally create the document and with each step write down what I did and more importantly, why I did what I did. Now when I make a misstep and have to go back and adjust, it’s the perfect opportunity to include a few comments of how to recover the system or what mistakes to avoid.
I’ve also found that by creating the documentation as I go, I can use the documentation to outline what I’m about to do which can help guide my efforts. I’ve always found that taking the time to think through what I’m going to do gathers my thoughts and seems to make me more productive. This works far better than trying to do something “on-the-fly”.
Tip #2 – Pictures are worth 1,000 words
It’s quite amazing to me how in a world that is driven by video, rich images and photographs that the documentation engineers create is almost entirely text driven. I can’t tell you how often I’ll come across documentation that includes almost no pictures whatsoever. I was recently working on a project where an engineer sent me a procedure for setting up a toolchain and deploying production code. The entire document was two pages that was not only difficult to follow but had missing steps and no pictures or diagrams! The engineer even assumed that the reader would know how to wire the development board up to a sensor without a wiring diagram!
While the text-based version could be used to repeat the original procedure, anyone following it would have to find several external, review schematics and make several leaps of faiths in order to successfully complete it. What should have been a one-hour process ended up requiring about four hours. If you are following the first tip which is to write your documentation as you go, taking screen shots of important steps in a procedure or taking a picture with a smart phone only takes about 30 seconds. The result can be documentation that is much clearer and saves the user (which could be the future you) a lot of grief.
Tip #3 – Have a colleague review the documentation
The last tip for us to discuss today, and one that should not be overlooked, is to have a colleague go through your documentation when you are done with it. As engineers, we often make assumptions that someone who comes after us will be thinking the same way that we are or that some information tidbit is obvious. Giving your documentation to a colleague to review will help to ensure that all the required information is included in the document so that if someone comes along later, they will be able to understand the process and reproduce or maintain the system.
A colleague can act as a great sounding board to ensure that everything is required. For example, I mentioned that I had a procedure that was provided to me that didn’t have any images. As I reviewed that procedure, I was able to point out screen shots, diagrams and images that should be added to the documentation that would make it easier for someone to understand what the procedure was and how to replicate it. Having no prior knowledge about the procedure and being forced to repeat it helped to provide critical feedback that resulted in a well-established procedure that is not easy to replicate.
Conclusions
These simple documentation steps might seem obvious, but I know for a fact there are lots of engineers that do not follow these simple tips. I come across lots of projects that are sparsely or not documented at all. It may seem obvious to the developer what needs to be done to use a code base, setup an experiment or whatever. The fact though is that it’s often not obvious and the same developer coming back a year later will often find it takes them time to figure out what they were thinking a year ago.
