Do you sometimes feel like your team spends more time documenting your system than building it?  One of the biggest hindrances to progress in a software project is documentation. The Agile Manifesto prescribes that teams should value working software over comprehensive documentation. It doesn’t mean that you should not create documentation; it means you should create documentation that provides value and at the same time does not hinder the team’s progress.

Writing comprehensive documentation for a system, especially at the beginning of a project, has many drawbacks. For example, if your team spends months documenting their requirements, analysis, design, and test cases there is a good chance that what you have documented will be out of date by the time you are done. In today’s business climate, needs change rapidly and that means the team needs to be able to adapt to changing requirements.

Another issue is that you may end up designing parts of the system that are not needed. Teams want to account for all the features that they think they might need. So teams waste effort and time by documenting features that may never get used.  Because so much time is spent up front generating documentation before any of the system is ever built, the team is delayed in delivering value to the business. This results in lost opportunity cost because you delay earning a return on your investment (Agilesphere, n.d.).

The best way to create documentation that provides value without hindering progress is to write tests for the system.  This is executable documentation that remains accountable to the realities of the working system. Automated tests greatly improve the quality of the software, which results in less defects and more confidence in the system.

Unit tests, functional tests, and integration tests all document how the system works for the developers. Unit tests validate the behavior of individual routines within the system. Functional tests validate how the different routines in the system will interact with each other.  Integration tests verify that all of the parts of the system work together as expected. Together, all of these tests provide accurate, living documentation of the system.  And this documentation is updated as the system evolves. However, while this documentation helps the developers, it does not help the rest of the team.

For the rest of the team, you can create documentation that provides value without hindering progress by creating acceptance tests. Acceptance tests serve as requirements documentation by describing how the various parts of the system will be used.  These tests provide the team with a way to exercise the system just as a user would. Often, teams use personas in their acceptance tests to represent users of the system and how they would interact with it (Carey, 2011).

All of these different types of tests allow the team to create working software and yet still create valuable documentation of the system. So for your next project, consider this approach and watch your team improve the value it provides to your company.

References

Carey, Jennifer. March 2011. Persona.

Agilesphere. n.d. Why Agile? Increased ROI.