The Practices of Agile Modeling (AM)

Agile Modeling (AM) defines a collection of core and supplementary practices, based on the principles of AM. Some of the practices have been adopted from extreme Programming (XP) and are well documented in Extreme Programming Explained. As with AM’s Principles, the practices are presented with a focus on modeling efforts so material adopted from XP may be presented in a different light.

The AM practices are organized into two lists, core practices that are highly recommended when taking an Agile Model Driven Development (AMDD) approach and supplementary practices that you should adopt as needed. There are also some really good ideas which you should consider adopting but which aren’t part of AMDD. There is a third list, deprecated practices which removed in the second release of the AMDD methodology in order to simplify it.

Core Practices	Supplementary Practices
Active Stakeholder Participation Apply the Right Artifact(s) Collective Ownership Create Several Models in Parallel Create Simple Content Depict Models Simply Display Models Publicly Iterate to Another Artifact Model in Small Increments Model With Others Prove it With Code Single Source Information Use the Simplest Tools	Apply Modeling Standards Apply Patterns Gently Discard Temporary Models Formalize Contract Models Update Only When It Hurts

Core Practices:

Active Stakeholder Participation. An expansion of XP’s On-Site Customer which describes the need to have on-site access to users that have the authority and ability to provide information pertaining to the system being built and to make pertinent and timely decisions regarding the requirements, and prioritization thereof. AM expands XP’s On-Site Customer practice to have stakeholders — including direct users, their management, senior management, operations staff, and support (help desk) staff — actively involved in the initiative. This includes making timely resourcing decisions by senior management, public and private support for the team by senior management, active participation of operations and support staff in the development of requirements and models pertaining to their respective areas. You can easily promote active stakeholder participation on your teams if you adopt inclusive modeling techiques.
Model With Others. When you Model With a Purpose you often find that you are modeling to understand something, that you are modeling to communicate your ideas to others, or you are seeking to develop a common vision on your team. This is a group activity, one in which you want the input of several people working together effectively. You will often find that your development team needs to work together to create the core set of models critical to your initiative. For example, to develop the metaphor or architecture for you system, you will often need to model with a group of people to develop a solution everyone agrees on as well as one that is as simple as possible. Most of the time the best way to do this is to talk the issue through with one or more people. Modeling with others is an example of “Non-Solo Development”, as is pair programming.
Apply The Right Artifact(s). Each artifact has its own specific applications. For example, a UML activity diagram is useful for describing a business process, whereas the static structure of your database is better represented by a physical data or persistence model. Very often a diagram is a better choice than source code — If a picture is worth a thousand words then a model is often worth 1024 lines of code when applied in the right circumstances (a term borrowed from Karl Wieger’s Software Requirements) because you can often explore design alternatives more effectively by drawing a couple diagrams on whiteboards with your peers than you can by sitting down and developing code samples. The implication is that you need to know the strengths and weaknesses of each type of artifact so you know when and when not to use them. Note that this can be very difficult because you have Multiple Models available to you, in fact the Agile Models Distilled page lists over 35 types of models and it is by no means definitive.
Iterate To Another Artifact. When you are working on a development artifact — such as a use case, CRC card, sequence diagram, or even source code — and find that you are stuck then you should consider working on another artifact for the time being. Each artifact has its strengths and weaknesses, each artifact is good for a certain type of job. Whenever you find you are having difficulties working on one artifact, perhaps you are working on a use case and find that you are struggling to describe the business logic, then that’s a sign that you should iterate to another artifact. For example, if you are working on an essential use case then you may want to consider changing focus to start working on an essential UI prototype, a CRC model, a business rule, a system use case, or a change case. By iterating to another artifact you immediately become “unstuck” because you are making progress working on that other artifact. Furthermore, by changing your point of view you often discover that you address whatever it was that causing you to be stuck in the first place. See the essay Iterate to Another Artifact for more thoughts.
Prove It With Code. A model is an abstraction, one that should accurately reflect an aspect of whatever you are building. But will it work? To determine so, you should prove your model with code. You’ve developed a sketch of an HTML page for accepting billing address information? Code it and show the resulting user interface to your users for feedback. You’ve developed a UML sequence diagram representing the logic to implement a complex business rule? Write the testing code, the business code, and run the tests to ensure that you’ve gotten it right. Never forget that with an iterative approach to software development, the norm for the vast majority of initiatives, that modeling is only one of many tasks that you will perform. Do some modeling, do some coding, do some testing (amongst other things).
Use The Simplest Tools. The vast majority of models can be drawn on a whiteboard, on paper or even the back of a napkin. Whenever you want to save one of these diagrams you can take a picture of it with a digital camera, or even simply transcribe it onto paper. This works because most diagrams are throwaways; their true value comes from drawing them to think through an issue, and once the issue is resolved the diagram doesn’t offer much value. As a result a whiteboard and markers are often your best modeling tool alternative: Use a drawing tool to create diagrams to present to important stakeholders and occasionally use a modeling tool if and only if they provide value to my programming efforts such as the generation of code. Think of it like this: If you’re creating simple models, often models that are throwaways because if you are modeling to understand you likely don’t need to keep the model(s) around any more once you do understand the issue, then you likely don’t need to apply a complex modeling tool.
Model In Small Increments. Incremental development in which you organize a larger effort into smaller portions that you release over time, hopefully in increments of several weeks or a month or two, increases your agility by enabling you to deliver software into the hands of your users faster.
Single Source Information. Information should be stored in one place and one place only. In other words, not only should you apply the right artifact you should also model a concept once and once only, storing the information in the best place possible. When you are modeling you should always be asking the questions “Do I need to retain this information permanently?”, “If so, where is the best place to store this information?” and “Is this information already captured elsewhere that I could simply reference?”. Sometimes the best place to store information is in an agile document, often it’s in source code. Read here for more details.
Collective Ownership. Everyone can work on any model, and in fact any artifact on the team, if they need to.
Create Several Models in Parallel. Because each type of model has its strengths and weaknesses no single model is sufficient for your modeling needs. For example when you are exploring requirements you may need to develop some essential use cases or user stories, an essential UI prototype, and some business rules. In combination with the practice of iterating to another artifact agile modelers will often discover that they are far more productive working on several models simultaneously than if they are only focusing on one at any given time.
Create Simple Content. You should keep the actual content of your models — your requirements, your analysis, your architecture, or your design — as simple as you possibly can while still fulfilling the needs of your stakeholders. The implication is that you should not add additional aspects to your models unless they are justifiable — if you do not have a requirement to add system auditing features then don’t add that features to your models. Have the courage to trust that you can in fact add this feature when, and if, it is ever asked of you. This is along the lines of XP’s practice of Simple Design.
Depict Models Simply. When you consider the potential diagrams that you could apply (UML diagrams, user interface diagrams, data models, and so on) you quickly realize that the majority of the time you only require a subset of the diagramming notation available to you. A simple model that shows the key features that you are trying to understand, perhaps a class model depicting the primary responsibilities of classes and the relationships between them, often proves to be sufficient. Yes, you could model all the scaffolding code that you will need to write, all the getter and setter operations that your coding standards tell you to use, but what value would that add? Very little.
Display Models Publicly. You should display your models publicly, often on something called a “modeling wall” or a “wall of wonder.” This supports open and honest communication on your team because all of the current models are quickly accessible to them, as well as with your stakeholders because you aren’t hiding anything from them. Your modeling wall is where you post your models for everyone to see; the modeling wall should be accessible to your development team and other stakeholders. Your modeling wall may be physical, perhaps a designated whiteboard for your architecture diagram(s) or a place where you tape a printout of your physical data model. Modeling walls can be virtual, such as an internal Web page that is updated with scanned images. See Ellen Gottesdiener’s Specifying Requirements With a Wall of Wonder for a similar viewpoint.

Supplementary Practices:

Apply Modeling Standards. This practice is renamed from XP’s Coding Standards, the basic idea is that developers should agree to and follow a common set of modeling standards on a software initiative. Just like there is value in following common coding conventions, clean code that follows your chosen coding guidelines is easier to understand and evolve than code that doesn’t, there is similar value in following common modeling conventions. There is a wide variety of common modeling standards available to you, including the Object Management Group’s Unified Modeling Language (UML) which defines the notation and semantics for common object-oriented models. The UML provides a good start but it isn’t sufficient — as you can see in Be Realistic About The UML not all possible modeling artifacts are encompassed by the UML. Furthermore, it says nothing about modeling style guidelines to create clean-looking diagrams. What is the difference between a style guideline and a standards. WRT to source code, a standard would be to name attributes in the format attributeName whereas a style guideline is to indent the code within a control structure (an if statement, a loop, …) by one unit. WRT to models, a standard would be to use a square rectangle to model a class on a class diagram and a style guideline would be to have subclasses placed on diagrams to the south of their superclasses.
Apply Patterns Gently. Effective modelers learn and then appropriately apply common architectural, design and analysis patterns in their models. However, as Martin Fowler points out in Is Design Dead? developers should consider easing into the application of a pattern, to apply it gently. This reflects the value of simplicity. In other words, if you SUSPECT that a pattern applies you should model it in such a way as to implement the minimal amount you need today but that makes it easy to refactor it later when it is clear that applying the full-fledged pattern is in fact the simplest approach possible. In other words, don’t over model. For example, you may recognize a good spot in your design to apply the GoF’s Strategy pattern, but at the current moment you only have two algorithms to implement. The simplest approach might be to encapsulate each strategy in its own class and build an operation that chooses them appropriately and passes them the appropriate input. This is a partial implementation of Strategy that leaves you in a position to refactor your design if more algorithms need to be implemented, yet does not require you to build all the scaffolding that Strategy requires — an approach that enables you to ease into application of the pattern.
Discard Temporary Models. The vast majority of the models that you create are temporary/working models — design sketches, low fidelity prototypes, index cards, potential architecture/design alternatives, and so on — models that have fulfilled their purpose but no longer add value now that they have done so. Models quickly become out of sync with the code, and there is nothing wrong with that. You must then make the decision to synchronize the models if doing so adds value to your team or to simply discard them because the investment to update the models won’t be recouped by the value of having done so (there’s negative payback). This practice is particularly important for agile documentation.
Formalize Contract Models. Contract models are often required when an external group controls an information resource that your system requires, such as a database, legacy application or information service. A contract model is something that both parties should mutually agree to and mutually change over time if required. Examples of contract models include the detailed documentation of an application programming interface (API), a file layout description, an XML DTD or a physical data model describing a shared database. As with a legal contract, a contract model often requires you to invest significant resources to develop and maintain the contract to ensure that it’s accurate and sufficiently detailed. Your goal is to minimize the number of contract models for your system to conform to the XP principle of traveling light. Note that you will almost always use an electronic tool to develop a contract model because the model must be maintained over time.
Update Only When It Hurts. You should update a model only when you absolutely need to, when not having the model updated is more painful than the effort of updating it. With this approach you discover that you update a smaller number of models than you would have in the past because the reality is that your models don’t have to be perfect to provide value. The street map that I have to my town is over five years old, I know this because my own street doesn’t appear on it and it’s been in place for a little over five years, yet the map is still useful to me. Yes, I could purchase an updated map, one comes out every year, but why bother? Missing a few streets isn’t painful enough to warrant this investment, it simply doesn’t make sense to spend the money to purchase a new map every year when the one that I have is good enough. Too much time and money is wasted trying to keep models and documents in sync with source code, an impossible task to begin with, time and money that could be better spent developing new software. This practice is particularly important for agile documentation.

Really Good Ideas:

The following practices are complementary to AM but are not explicitly included as a part of it:

Refactoring. This is a coding practice in which you make small changes, called refactorings, to your code to support new requirements or to keep your design as simple as possible. From the view of AM this practice ensures that your design remains clean and clear as you work on your code. Refactoring is an integral part of XP. You can read more about code refactoring and database refactoring here.
Test-First Design. This is a development practice where you first consider and then code a test case before writing the business code which satisfies this test case. From the point of view of AM this practice forces you to think through your design before you write your code, removing the need for detailed design modeling. Test-first design is an integral part of XP and you can read more about it here.

Practices Deprecated From Agile Modeling Version 1

To simplify AM, I chose to remove several practices in January of 2005. Although these are still valid ideas which are not going away, they won’t be considered “first order practices” anymore. I found over the years that as I training and mentored people in AMDD that I didn’t need to discuss them very much for people to understand the approach. The practices which I removed are:

v1 Practice	Description	Reason for Removal
Consider Testability	When you are modeling you should be constantly asking yourself “How are we going to test this?” because if you can’t test the software that you are building you shouldn’t be building it. Modern software processes include testing and quality assurance activities throughout the entire lifecycle, and some even promote the concept of writing tests first before writing software (this is an XP practice).	Although this is a great idea but when you’re taking a TDD approach, which most agilists do, along with an AMDD approach you find that this practice becomes moot.
Model To Communicate	One reason to model is to communicate with people external to your team or to create a contract model. Because the customers for some models are outside your team, you may need to invest the time to make your model(s) look “pretty” by using electronic tools such as word processors, drawing packages or even sophisticated CASE tools.	This is a great motivator for modeling, but not really a practice, therefore I deprecated it.
Model To Understand	The most important application of modeling is to explore the problem space, to identify and analyze the requirements for the system, or to compare and contrast potential design alternatives to identify the potentially most simple solution that meets the requirements. Following this practice you often develop small, simple diagrams that focuses on one aspect of your software, such as the lifecycle of a class or the flow between screens, diagrams that you often throwaway once you are finished with them.	I removed this for the same reasons that I removed modeling to communicate.
Reuse Existing Resources	There is a wealth of information that agile modelers can take advantage from. For example, perhaps some analysis or design patterns are appropriate for you to apply gently to your system. Or perhaps you can take advantage of an existing enterprise requirements model, business process models, physical data models or even models of how systems are currently deployed within your user community. It’s true that these models either don’t exist or are out of date in many organizations, although you’re often likely to uncover reasonably accurate models with a bit of research.	This is a great idea which all developers should practice, but it’s a general concept which goes beyond modeling and documentation.

Translations

Japanese