Project documentation and Agile development
Agile development has been very effective at reducing the need for extensive, ponderous documentation. However, this methodology has not done away with the need for documentation entirely. It has simply moved documentation from a foundational role to a supportive role.
Tips for Agile documentation
Agile development has been very effective at reducing the need for extensive, ponderous documentation. However, this methodology has not done away with the need for Agile project documentation entirely. It has simply moved documentation from a foundational role to a supportive role. Here are 7 ways your team can use documentation in a way that enhances Agile development rather than slowing things down.
1. Focus on reality
Documentation is not the same thing as planning – and it’s certainly not the same thing as brainstorming. When you are working within the Agile framework (or any other project methodology for that matter) there’s no telling how a project will evolve over time, which is why advance documentation is such a nightmare. It makes much more sense to document what you have actually done and how it really works than to document what you are going to do and how it might work. Making guesses may lead to going back rewriting former documentation. At the same time, understand that the documentation itself may need to be flexible enough to change over time. Even in the best of circumstances, it isn’t something you can do once and then simply put on the shelf.
2. Document decisions
While much of the work of documentation is reserved until the end stages of an Agile project, it is still important to take notes during the earlier phases. One of the most important types of information to record is the rationale behind why certain critical decisions were made. This avoids the problem of second-guessing and justifying decisions later. You may need to be able to say, “We decided, as a team, after reviewing information ‘xyz’ that approach ‘a’ is a better option than approach ‘b’ for the following reasons…” This clarification may mean less backtracking and finger pointing. After all, if it was a good decision at the time, what changed between then and now?
3. Who needs to know?
No development project is fully transparent. There will always be some parties who need to be able to understand what’s going on behind the code. This might be a third party collaborator who isn’t able to be fully integrated into the intense team relationship of the Agile environment. Or, it might be future “generations” tasked with maintaining the software. Determine who your audience is so you can target your documentation correctly and cut down on wasted explanations.
4. Use your writers appropriately
This means using code writers to write code and technical writers to help with documentation. Your developers should be the ones doing the initial documentation to ensure it is relevant and accurate. Your technical writers should be polishing the documentation to ensure it is readable and helpful. Make technical writers part of your team so they can fully collaborate in this process rather than just having stuff handed off to them at the end.
5. Favor accuracy and brevity
One of the biggest problems with overly extensive documentation (besides the fact that it slows a project down without adding value) is that it is usually full of errors. It makes more sense to focus energy and resources on debugging code than on debugging your documentation. This tip goes along with tip #4. So, be sure your technical writers understand that part of their job is to help organize material into its most concise form for most types of documentation throughout the project. Providing lots of detail is usually only important in user documentation since that’s the content you know will be accessed and relied upon the most throughout the lifecycle of an application.
6. Use self-documenting code
This is not always the best alternative to using commenting. However, getting in the habit of writing code that is clearly labeled with its purpose and its intent is a good idea. Use comments for clarification when the code itself simply can’t be written in a way that is self-explanatory. This shift toward self-documenting code is very much in line with the Agile concept because it tends to evolve naturally with any changes that occur during development.
7. Do the minimum required
Some forms of documentation may very well be seen as a requirement rather than simply an option by the stakeholders of your project. There may be some room for negotiation on this point if you can show that there are alternate ways to give the client what they really want rather than what they think they want. However, when push comes to shove, your team should be prepared to provide documentation that matches the client’s baseline expectations. If you deliver a stellar outcome on your first project, the stakeholders may relax the reins a little next time.
