David G. Prenshaw

“Noooooo!! Don’t say the ‘D’ word!!!”  That’s what most developers say when they hear the word “Documentation.”  No, it doesn’t sound snazzy like the latest JavaScript library or other cutting-edge technology.  But is it important?  Absolutely.  Sometimes it can be really difficult to realize the value in good, readable, and thorough documentation.

I recently spent a period of about 2 weeks chugging away at documenting a large module of our application.  Many of the business rules had never been documented before, while some had been established during the last release.  It seemed to be a sort of “business rule soup” trying to wade through all the existing (and sometimes out of date) documentation and consolidate it into a up-to-date module document.  Through the process, I came away with 6 reasons why it is so important to have good, thorough documentation:

1. The people testing your software can know how to test it.  Obviously, you want the people testing your code to know how it works so that they can test it correctly.  Out-of-date documentation or documentation that is not put in human readable terms (e.g. someone off the street can understand what’s going on) is not going to help your testing staff.  The more business rules you document, the more bugs the testing staff can find!  How will they know if there’s a bug if they don’t know how the page is supposed to work?
2. Other people on your development team can learn about how your software works. With many large teams, it can be difficult for every member to be familiar with every single piece of the software.  With good documentation, if a team member with no experience working on your software is assigned to add a feature to it, they can simply refer to your documentation to understand the intricacies of how it works, and the business rules it should enforce.
3. You can remind yourself of what you wrote.  Let’s face it.  People sleep.  We forget things.  If I work on a feature back in January, and November comes around, chances are that I probably won’t remember what I did back in January.  With good documentation, I can refresh my memory of what exactly I did in the code, without having to trace through huge bits of (probably uncommented) code to try and understand what all is going on.
4. People new to the project can learn how it works.  Pretty self-explanatory…documentation is great for onboarding new members to projects.  If they are going to be writing code one day, they better understand how the existing code works, first!
5. You will find bugs in the software.  When thoroughly documenting a piece of code, especially ones that haven’t been documented correctly, it will require you to heavily test every single business rule present and determine the source of every single piece of data.  Sometimes you may find that some rules are partially enforced, or maybe aren’t enforced at all.  Perhaps people thought the code behaved one way, but after attempting to document it… Woops!! Doesn’t behave that way!
6. You will have less false bugs reported by the testing staff.  It’s important that business rules are documented, but they must be correct! With thorough documentation that is correct, there will be little chance that a bug will be thrown at you, when the real problem is incorrect documentation.

See!  It’s pretty important after all!  Although documentation can be a bear to write at times, it can be your best friend in the long run!