Tag Archives: agile modeling

Here is an example pattern from Agile Adoption Patterns: A Roadmap for Organizational Success:

Definition: Documents are created that evoke memories, conversations, and situations that are shared by those who wrote the document.  They are more meaningful and representative of a team’s understanding of the system than traditional documents.

Business Value: Evocative documents help prolong a product’s lifetime by accurately representing the team’s internal model of the software and allowing that model to be handed down from master to apprentice.  The better understanding of the system over time also reduces the maintenance cost of the system over time because appropriate changes reduce the deterioration of the software. 

Sketch: Aparna and Dave were on their way home from a week long UML training course and discussing what they had learned.  “UML certainly provides a rich and detailed tool for describing our software,” Dave noted.  “But it can still be misleading,” Aparna responded. “Remember our discussion about the customer class?”  “I do,” said Dave, “and I remember how we got into that discussion of what ‘is’ is – when people started using our UML description  as if it was a customer.”  “Oh yes, and that guy in the back talking about Alfred Korzybski and ‘the map is not the territory,’ that was weird,” Aparna added.  “But he was right, really,” continued Dave. “No matter how much detail you get in your UML model and templates, something is always missing.  The model is never the real thing.”  “And our understanding of what the real thing is keeps changing, and changes from one context to another,” Aparna said. “How can we put all of that in a model?”  “Well,” Dave suggested, “we probably don’t need to if we can find a way to remind ourselves of everything we know about something when we need it.”  “How would we do that?” Aparna asked.  “Remember that icon on the wall of the seminar room,” Dave enquired. “Remember when we asked the facility manager about it and she talked for half an hour about its meaning and history, and everything.”  “Sure do,” Aparna responded. “One simple symbol evoked a huge amount of memory.  Maybe that is the secret …”

Context: You are on a software development project where product lifetime and reducing the cost of software are important – you are building a system to last for several years.  Documentation isn’t working – as a document is passed from one person to another much of the context and value is lost, and as a result, the maintenance team’s understanding of the codebase constantly deteriorates.  This is resulting in the calcification of your software system. 

Forces: 

1. Literate and legalistic societies and organizations share a deeply held, though often non-conscious, belief that written documents are representative in nature.

2. A contract IS the agreement among parties to the contract.  The blueprint IS the building, albeit in a different format.  

3. The specification IS the software artifact desired.  This belief is so strong in the arena of software that many believe that it should be possible to formally and mechanically transform specifications into an artifact with no interpretation or ambiguity.

4. Documents that are built collectively – by having a conversation – are much more valuable to those who were part of the conversation.  These documents are evoke memories of the conversation, its context, and much more than what is merely written on paper.

5. Agile development is the embodiment of group “theory building” as described by Peter Naur [Naur 1985].  That is, the software we build is directly related to a mental model – the ‘theory’ – that the programmers share.  To impart this model to others traditional documents fail miserably.  Naur suggests that the only successful way to share this model is through apprenticeship.

6. Agile practices, more than any other kind of development practice, require the creation of a rich and easily accessible “external memory”.

7. Representational documentation is notoriously limited and has a long track record of failure in supporting “theory building” and acting as an “external memory.”

Therefore:

All documentation should be evocative rather than representational.  Anyone that has read a good novel is familiar with the notion of an evocative document – one that enables the reader to “recall to mind” thousands of sensations, emotions, even details of time and place that the author could not possibly have included in the text of the novel.  

This is how you can truly preserve the shared knowledge and understanding of the team and pass it along to new members.  There is no “one way” to put together such a document, so the distinguishing factor in an evocative document is that it is a reminder of the real information and knowledge in a person’s head – it is not the knowledge itself. It is not directly representational.

A team that relies on evocative documents spends more time in face-to-face conversation and less time building and maintaining documents.  The documents they keep tend to be simple and only comprehensible to those in the conversation – therefore to transfer the knowledge behind the document to someone who was not there, the conversation and context have to be repeated and the document built from scratch.  What is gained by this is a much better transfer of knowledge within context that ultimately leads to more proper understanding of the application and reduced maintenance costs.  

More specifically, evocative documents tend to have the following characteristics:

1. • Informal – 3×5 cards rather than syntactically correct and detailed UML diagrams.

2. • Natural language based – both in terms of the natural language used by the team for communication inside and outside the office, but also in terms of the domain driven vocabulary of the project itself.

3. • Rich in references to people, time, and place.

4. • Contextual in nature, photos that are rich in color and detail communicate much more than simple UML diagrams. 

Evocative documents are an external memory to a previous conversation.  Evocative documents have value to those who took part in the conversation.  To share such a document with someone who was not part of the conversation they must reconstruct it with someone who was part of the original conversation.  This means that evocative documents are not very scalable.  (The problem is that neither are traditional documents, we just assume they are and are unaware of/ignore the information loss and corruption.)  

But:

Your documentation has probably slipped into representational form and is no longer evocative if:

1. It takes longer to produce the documentation than it does to comprehend and use it.

2. Anyone in the organization begins to express a belief that the documentation has intrinsic value and not just utilitarian value.

3. Documentation that is highly stylized and that uses precisely defined and context free syntax (e.g., UML) will almost certainly be perceived as representational rather than evocative.  However, it need not be, as long as it brings up a shared conversation and/or experience.

4. There is any kind of movement to make the documentation archival.

5. Specialists are employed to produce the documentation.  There is an exception to this rule:, technical writers (who should really be more novelist than tech writer) charged with producing manuals and books for users of the software that were prevented from participation in its creation.

Variations:

Agile modeling, as originally described by Scott Ambler, is a form of just-in-time modeling.  People model to have a conversation and then take a digital photo of that model to remind them of the conversation.  This is a form of evocative document that uses highly stylized languages such as UML.

One last note on evocative documents – they point out a limitation of our current culture and what many of us take for granted.  Accepting the value of evocative documents means rejecting the notion of accurately communicating detailed information in context by writing them down.  You have to have a conversation, the document is there only as a reminder.  As the eminent American philosopher, Dr. Phil says “how’s that working for you?” – how have the reams of requirement, design, and planning documents been working for us?

References:

Ambler, S., and Jeffries, R., Agile Modeling: Effective Practices for Extreme Programming and the Unified Process, Wiley, 2002.

Dahlstrom: external memory

Larman, C., Applying UML and Patterns: An Introduction to Object Oriented Analysis and Design and Iterative Development 3rd edition, Addison Wesley, 2004. 

Korzybski, A., Science and Sanity: An Introduction to non-Aristotelian, Systems and General Semantics (5thedition), Institute of General Semantics, 1994.

Map-territory relation, Wikipedia, http://en.wikipedia.org/wiki/Map-territory_relation, accessed November 2007.

Naur, P., “Programming as Theory Building,” Microprocessing and Microprogramming, 15:55, 253-261, North Holland, 1985.  (Also reprinted in Cockburn’s Agile Development)