Your development team spends a lot of time creating formal functional specifications, design documents, and general documentation. They create a nice class diagrams, sequence diagrams, or flowcharts to be included. Sounds like your team did everything it should, right?
Well, not exactly. Where is the software? Documentation is nice, but one thing that I learn is that creating developer documentation is seriously overrated. The documentation end up being practically worthless in the end, mainly because of simple, organic growth of your software.
In many organizations, any documentation that does exist are most likely out of date, because no one wants to update them. The documents end up in some hole on your company’s intranet and will stay there forever. Even if your documentation is current, there is *no* guarantee that anyone would read or understand any of it. Other developers, QA analyst, business analysts and management don’t really want to read a 50-page document on your favorite piece of code. They will often skim it, with often a small subset of knowledge how it really works. As time passes, the amount of trust in documentation diminishes because the audience knows that the software changes.
I am not saying that there should be *no* documentation, but your documentation should be like a good book. It should captivate your audience and more importantly, be relevant to the current situation. The most valuable documentation has correct context and has need. Creating documentation for the sake of documentation will doom your project.
So, beautifully lean documentation is key to success. What does this mean? Well, there are many strategies for agile or lean documentation. However, to have beautifully lean documentation, I take a more minimalistic approach:
- The source code itself is probably the most valuable documentation any developer can have. Therefore, I make it a point to create meaningful comments and use documentation generation systems wherever possible.
- I think that the user stories provide better context for the software than any other written documentation. In essence, user stories detail what the software is suppose to do. Couple user stories with acceptance tests, the system becomes validated.
- If the software has external service interfaces, then those need services need explicit documentation. There is no real way around it. However, the documentation is used as reference at this point and it usually only documents the service interface.
- I normally document just the design decisions that I made. This gives developers an understanding of what I considered and, more importantly, what did *not* work. This will save other developers some time on research.
So, when I am working on a new product architecture, creating beautifully lean documentation allows me to concentrate on the software.