OpenSource Connections
Category: Uncategorized
Since I am posting this on Valentines Day, its appropriate that Ive chosen to discuss one of a developers great loves: Documentation.
Okay, so the truth is most developers really dont enjoy writing documentation. Its much more fun to write code. And Agile development methods discourage writing a lot of documentation, with very good reason. Agile focuses on “Working Software over Comprehensive Documentation”.
In “Agile Principles, Patterns, and Practices in C#”, authors Robert Martin and Micah Martin declare:
“Martins First Law of Documentation: Produce no document unless its need is immediate and significant.”
Scott Ambler has written a very interesting, and dare I say, big document about “Agile/Lean Documentation: Strategies for Agile Software Development”. He points out that theres nothing wrong with doing documentation, even in an agile environment, and that sometimes it is the best way to communicate with external parts of your team or clients who you dont see every day. But he makes a long list of critical points that emphasize your project should not be driven by documentation. Some of my favorites from his article:
* The fundamental issue is communication, not documentation.
* Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
* The benefit of having documentation must be greater than the cost of creating and maintaining it.
* Ask whether you NEED the documentation, not whether you want it.
* Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
Perhaps the most important point he makes, and agile methodologies emphasize, is that “Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.” Amblers point seems to be that you should spend your time refactoring your code, and providing a solid test suite so that you have executable requirements and your code can be easily verified.
Thats all true, and I would also add that excessive documentation can lead to project failure especially if you spend too much time up front on a project writing documentation about how youre going to eventually write your code. I believe thats what Ambler is getting at when he says you should “Document stable things, not speculative things.”
However, there are situations where a lot of documentation is required, and so we need to consider how to integrate that with Agile environments.
One simple situation is when you are a consultant on a project, and the client does not have a lot of in house expertise in the technology you used for the project. Agile methodology says you should focus on communication within your team and that is more effective than documentation. That is the ideal situation when there are other technical people to communicate with, but especially as a consultant, your clients will often require certain documents so they can keep the system going after you leave.
Another situation is working with government agencies. Some agencies are going to require certain list of documents be written for every project. When a corporate client makes a requirement like that, you may be able to convince them not all of it is necessary. But in the case of some government agencies, they may be required by law or an oversight agency to always produce certain documents.
In those situations, all you can do as a consultant is to maximize your efficiency in development while still meeting their documentation requirements. Following these tips may help when you have to integrate large volumes of documentation into an Agile project:
- At the beginning of the project, find out from the client exactly what documentation they require
- Go through the list and identify which ones will be helpful early in the project and will facilitate communication with the client before code is written. For example, a system overview diagram or high level use case may be helpful to ensure everyone understands the high level operations you are trying to achieve with the code. But there is not much value in coming up with a detailed class diagram before you write iterative code which would instantly make that diagram obsolete.
- Keep the up front critical documentation to a bare minimum (a couple of days maximum), and quickly get to the point of writing and demoing even very basic code to the client.
- Save the other documentation which the client requires until the end of the project, and if possible until after your first release to their customers. Then you can easily create a document like a class diagram without having to worry about the code changing as much.