Agile Software Configuration Management: Communications and Documentation

Regarding tracing requirements (stories) to code changes... if it's required (for whatever reason), might not a checkin or checkout comment simply identify the corresponding story? Seems to me that would do it for tracing to unit-tests too. So that takes care of the cards and code.

Now maybe not all agile projects use index cards as the sole means of requirements capture (cards are often just an initial capture mechanism, with a tool being used to store and track/sort/report the requests for features and fixes.), but the basic idea is the same: Placing the related (traceable) information in the same "storage" container minimizes the burden of maintaining linkages.

This is the essence of applying the LoRD principle! Ideas such as "Literate Programming" and the ability to declare variables in C++ and Java just before their use (instead of "up front" at the very beginning) are all based on this same principle of locality of reference!

Configuration Item Identification/Reports
Regarding creating CI reports, managing dependencies between them and keeping them up to date with the actual code... from an agile perspective, today that happens during the build process. Build time is when we can capture the actual CI's for that release, know the dependencies between them and can relate them to the actual code with confidence that they won't change for that release.

In the future when "Model-Driven Development" and MDA tools are more mature, we predict they will become the source of configuration and build information (in keeping with the ideal of round-trip engineering and minimizing the "cognitive distance" between the description of the system and the working system itself):

• The Implementation View and Deployment Views of the UML-based 4+1 views of architecture [4] already have the elements necessary to model the configuration items (CIs) and their dependencies, and to capture their "attributes" and associations with other entities in the other views (such as classes/objects).
• What they don't currently have is the ability to automatically create and update/maintain the dependency information or a way to associate ANT/Make recipes and actions so that the build script itself (or at least its dependencies) can be auto-generated.

The Litmus Test
Should we formally document or not? Here are some questions that can help us decide for our project:

1. Is the document central to the overall objective/goal of your project? If the document discusses some part of your project that can be better served by discussing it in person, question the expenditure of resources to put it to paper.
2. Does the document really require persistence?  It's not uncommon to have project documents that are created without considering this question.  Is it really necessary to have a document that describes the thought process behind the development methodology in use?  If so, make sure that the information is somewhat stable and closely managed to the CI that it is written for - and furthers the team to the project goal.  If not, the expense in creating and maintaining the information in manual, textual means will outweigh the benefit it provides and result in a waste of resources.
3. Are you trying to communicate to many people?  Documents can be efficient in the sense that we can write them once and speak to many listeners. They are inefficient in the sense that they are substantially less effective in communicating than conversation.
4. Manual processes versus automated processes: Is there a way to automate a procedure instead of documenting it?  Well documented manual builds are a classic example of a situation where the project would typically be far better off by automating the build and letting the automated build script become the document - effectively making the separation between the document and source zero.
5. How close is the document to the actual CI that it represents?  When creating the document, look for ways to close the gap between the document and the source it refers to.  This will minimize the expense in maintaining the document over time.

Summary
Agile software configuration management is an approach requiring significant discipline from participants.  It's very focused on building quality into the software and in releasing more software in a shorter period of time.  A more effective way of communicating agile concepts is through the use of metaphors.  

Different projects have different tolerances for risk, which will dictate the amount of knowledge traceability required.  The LoRD principle tells us that the cost of knowledge traceability approaches zero as the distance between the two knowledge references becomes closer. Therefore, when we do require documentation for a project, for whatever reason, work to bring the documentation as close as possible to the referenced item it discusses. This will significantly reduce the opportunity for the document to become out of date as well as reduce the cost of maintaining that document.

References

[1] Managing Software for Growth: Without Fear, Control, and the Manufacturing Mindset, by Roy Miller; Addison-Wesley, July 2003
[2] Balancing Agility and Discipline: A Guide for the Perplexed, by Barry Boehm and Richard Turner; Addison-Wesley, August 2003
[3] Locality of Reference Documentation, by Brad Appleton; drafted January 1997. http://c2.com/cgi/wiki?LocalityOfReferenceDocumentation
[4] The "4+1" View Model of Software Architecture, by Phillipe Kruchten; IEEE Software Vol. 12 No. 6 (November 1995).
[5] Agile Documents Discussion, from agile-testing discussion group on Yahoo.com; December, 2003 http://groups.yahoo.com/group/agile-testing/message/2814   
[6] People Factors in Software Management: Lessons From Comparing Agile and Plan-Driven Methods, by Richard Turner and Barry Boehm; in CrossTalk: December, 2003
[7] Agile Software Development: The Business of Innovation, by Jim Highsmith and Alistair Cockburn; IEEE Computer: September 2001 (Vol. 31, No. 9), pp. 120-12