Agile Requirements Modeling Example 1. Initial Envisionment

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 1 of 133/1/2011Agile Requirements Modeling ExampleSearch Home | AMDD | Best Practices | Architecture |Requirements | Analysis | Design | Documentation | Models | Modeling Style | Contact Us | Mailing List |FAQHow would you go about modeling the requirements for a business application in anagile way? Let’s consider an example, in this case how you could approach modelingthe requirements for the SWA Online case study on an Agile Unified Process (AgileUP) project. Before doing so there are several issues that you must be cognizant of:1. The focus of this article is requirements modeling. Whenever the discussion strays into territory thatpertains to another type of modeling – analysis, architecture, or design – I’ll stop the discussion. Agilesoftware development is highly iterative, and as a result the lines between requirements and otherforms of modeling quickly become blurred in practice.2. This is one of many ways that you could take and still be considered agile. Remember, AM is apractices-based methodology, it does not define a specific, prescriptive way to work and therefore thereare many ways to apply it appropriately. Don’t worry, I’ll point out other alternatives that I may havechosen at various points but please keep an open mind.3. The SWA Online team is following an Agile UP process, therefore artifacts such as use cases will play animportant role in the requirements modeling process. Had they taken more of an eXtreme Programming(XP) approach user stories would instead dominate. See the AM and XP where I discuss this casestudy from an XP point of view.4. As I wrote this article I found it much easier to discuss my approach as if it had actually happened eventhough the case study is fictitious and merely based on my experiences at real organizations building e-commerce systems.5. It is best to think about requirements modeling from two different points of view: initial modeling anddetailed model storming.1. Initial EnvisionmentInitial requirements modeling occurs at the beginning of the lifecycle of your project, in the case of the AgileUP during the Inception phase and The Eclipse Way during the Warm-Up iteration. With an Agile ModelDriven Development (AMDD) approach this occurs during "iteration 0". During this effort there are three maingoals:1. To identify the scope, at least at a high level, of the system that you are building so as to define theboundary of your efforts.

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 2 of 133/1/20112. To define the high-level requirements for your system.3. To build a consensus amongst your stakeholders and within your development team as to what therequirements imply.The initial requirements envisionment effort can be as short as a few hours, particularly if you are co-locatedwith your project stakeholders and they are able to come to a general consensus as to what the system shoulddo, or could stretch on for several days or even weeks in situations that are less than ideal (see OvercomingCommon Requirements Challenges). You will typically hold large modeling sessions, which typically:Are long, sometimes several days in length for large projectsHave many project stakeholders involved so as to hear the requirements from a wide range of peopleTend towards the formal end of the scale (often due to the larger number of people and sometimes dueto a lack of familiarity of your project stakeholders with more agile approaches)Include some developers, particularly when you want to start building an understanding within your teamof what the system is to accomplishThe scope of your system may be defined by a single statement, in the case of SWA Online it may besomething as simple as “To sell our products to customers via the Internet” or a statement with greater detailsuch as “To sell physical, but not virtual, products to existing or new customers in the Continental UnitedStates”. Your system scope may also be defined using a context model – a model showing how your systemfits into its overall environment – something that is often depicted using a use case diagram, as you see inFigure 2, or as a dataflow diagram (DFD) as in Figure 1 (this style of diagram is often called a “level-0” DFD).It is important to understand the scope of your system so as to limit your development efforts. The firststatement was too vague, it could be taken to mean that you are selling to international customers, asignificantly greater effort than selling only within the USA, as well as selling virtual products such as onlinemusic which would require the addition of an online delivery system as well as a physical one. You may findthat your scope changes over time, a decision to be made by your project stakeholders, so be prepared toembrace change.Figure 1. A data flow diagram (DFD) used to model the context of SWA Online.

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 3 of 133/1/2011Figure 2. A use case diagram used to model the context of SWA Online.

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 4 of 133/1/2011So which is the best artifact to describe the scope of your system? A statement, a DFD,or a use case diagram? Depends on your situation. Statements are straightforward butoften not as communicative as a diagram. The DFD of Figure 1 shows the system in thecenter of the diagram and its relationships with other external entities – organizations,people, or other systems – that are outside the scope of your control yet still interact withyour system. A major advantage of this approach is that it depicts in reasonable detail themajor flow of information between your system and the outside world. The use casediagram of Figure 2 takes a different tack, depicting the system in the center once againand the actors (organizations, people) that interact with your system. The mainadvantage of this approach is that it depicts both the external and internal actors thatinteract with your system, as opposed to the DFD that just depicts the external ones. Themain disadvantage is that it does not indicate any details regarding the interactionsbetween the system and the actors. Which diagram should you create? Both have theiradvantages and disadvantages, so perhaps you should consider creating both?Hmmmm… doesn’t sound very agile to me. A better approach would be to create onediagram, breaking the rules a bit and combining the best of both diagrams in one as I’vedone in Figure 3. Notice how I’ve indicated the internal entities with an “I” in the topcorner of the two entities, my own style, and dropped the numeric identifiers with theentities: id numbers are difficult to maintain manually and I’d rather have a rule that entitynames are unique and thus they can take on the role of the identifier if needed. I couldjust as easily used use case notation, although had I chosen to show data flow I wouldhave broken a serious use case modeling rule, but luckily my project stakeholders likedDFDs so I went with their preference. Remember that the principle Model With aPurpose recommends that you know your audience, enabling you to pick the artifactsbest suited to them.Don’t be afraid to break the rules. Although general practice is to not include internal entities on a level-0 DFD,the idea is that you introduce internal entities when you start digging into the details, I’ve chosen to do soanyway in Figure 3 because it enabled me to avoid drawing a second diagram. The important thing to notice isthat the world hasn’t come to an end and the modeling police haven’t charged me with software processmalpractice. Yes, I have arguably gone against the practice Apply Modeling Standards, but in doing so I havereduced both development and maintenance costs, which indicates to me that my organization may want torethink this standard if it becomes a huge issue for someone.Figure 3. A DFD including internal entities to model the context of SWA Online.

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 5 of 133/1/2011To identify the high-level requirements for a system I prefer to take a usage-based approach, one in which yourprimary focus is on how your users will work with the system. My experience is that this is a valid approach formost software development efforts because if you don’t understand how people will work with your system it isincredibly difficult for you to build software that will support and enhance the way that they work. I would usethis approach to build business applications to be used internally within your organization, for business softwareto be used by customers of your organization, for shrink-wrapped software (such as a CASE tool or wordprocessor), for the development of a data warehouse, and even for the integration of commercial off the shelf(COTS) systems such as SAP R/3 or Oracle Financials. In the case of a data warehouse a common mistake isto gather “data requirements”, lists of data elements and/or data entities that people want to store in the datawarehouse, an approach that seems like a good idea at first but if you don’t know how people intend to workwith that data then it is difficult to prioritize your effort or even know if you are providing what your projectstakeholders actually need. In the case of COTS systems you need requirements against which you canevaluate competing packages. Artifacts such as features, usage scenarios, use cases, and user stories aregood options for this. Following the practice Apply The Right Artifact(s) I would likely choose use cases todescribe SWA Online because SWA Enterprises used the Agile UP as the primary base for their softwareprocess and use cases fits best with this process. Had they chosen XP as the primary base then user storieswould be more appropriate or if Feature Driven Development (FDD) (Palmer & Felsing 2002) was the basethen features would have been my choice.Figure 4 depicts a high-level use case diagram, a digital picture of a whiteboard sketch, that I created with myproject stakeholders. This is an essential use case diagram because it shows a technology independent viewof the system – you could implement a fully manual system or a fully automated system based on this diagram.Yes, the use case “Post Product Review” could be better renamed “Write Product Review” to make it moregeneral but my project stakeholders chose the other name because it suited them better. I always strive to

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 6 of 133/1/2011make requirements as technology independent as possible but the reality is that many systems are alreadyconstrained to a subset of architectural options, for example SWA Online is constrained to an Internet-basedsolution, so investing time trying to abstract away from this constraint is likely of little value to your immediateefforts. Remember the principle maximize stakeholder ROI and focus your requirements modeling efforts ontasks that provide positive value.Figure 4. A high-level use case diagram for SWA Online.The use cases would be described simply, during your initial modeling efforts a point-form description of thelogic for each use case may be sufficient. You don’t need to specify the system in detail at this point, you onlyneed to gain a basic understanding of what the system should accomplish and to identify the initial scope for thesystem, and a point-form description of each use case and actor does this. If your project stakeholders allow ityou may not even need to go this far – perhaps identifying three or four use cases is enough for now. If it isthen apply the principle Model With A Purpose and stop your initial requirements modeling efforts for now,moving on to detailed modeling efforts that drill down into the modeling and implementing the requirements youhave already identified.In Figure 4 you see that I have applied the UML stereotype on a requirements diagram, yet in TheObject Primer 3/e I recommend that you apply stereotypes on analysis-level use case diagrams, typicallyreferred to as system use case diagrams because they often reflect architecture and design issues, but notrequirements-level use case diagrams. Once again the world hasn’t ended and the modeling police haven’tcharged me with crimes against software development humanity. The diagram is interesting because it showsthat it is common for models to cross process boundaries, in this case the diagram reflects what I wouldconsider to be both requirements and analysis issues.

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 7 of 133/1/2011It’s easy to say that you need to reach a common consensus between project stakeholders but much moredifficult to achieve it in practice, even if you have overcome the common challenges to requirementsefforts. Individual project stakeholders have different backgrounds, different priorities, and differentpreferences. To build a consensus everyone needs to recognize this fact, communicate what they need fromthe system, listen to what others have to say, and be prepared to work towards a common goal. Whenever I’mworking with a group that is having a problem coming to consensus we’ll write down everyone’s issues on aplain old whiteboard (POW) where everyone in the room can see and discuss them – this visually depicts theextent of the group’s differences and provides a focus for their discussion. Sometimes we’ll remove an issuefrom the board, or better yet simply cross it out because I often want to record scoping decisions (more on thissoon), after the originator of the issue recognized that it wasn’t required or at least wasn’t important as otherissues. I also like to draw lines between contradictory issues so as to highlight the need to discuss them, oftenusing a specific color of marker for just that purpose.As the group focuses on high-level usage requirements they will often identify related business rules andconstraints, as well as technical requirements and requirements that the system may or may not need to fulfill atsome point in the future. During initial modeling you should prefer “park” business rules, constraints, andtechnical requirements, often writing them on flip chart paper or on the POW, capturing just enough informationso that you know what the requirement is when you explore it in greater detail later. The goal is to get out ofinitial modeling as quickly as possible so you want to avoid investing time exploring details – when you start toexplore details in these initial requirement sessions you put your project at risk because you are not obtainingconcrete feedback regarding your work and of suffering from analysis paralysis. Remember the principleSoftware Is Your Primary Goal and not to produce models and documents describing what your software issupposed to do. For example, as in the initial requirements modeling session for SWA Online my projectstakeholders identified several business rules and constraints pertaining to fulfillment of orders, such as how topack certain types of goods, how some products have finite shelf lives, and the pick-up procedures of ourshippers. Whenever I hear requirement such as this I ask someone to write it down, either on the POW or onan index card that is then placed on a shared desk where everyone can see it.This leads to an important point: modeling sessions are interactive. Everyone participates. At the start anexperienced modeler will need to start the effort, explaining the techniques and prodding people to pitch in.This prodding may be something as simple as asking someone to come to the POW and explaining whatthey’re talking about, filling out an index card to summarize a business rule, or writing on a Post It note to recorda data requirement for a potential report. As people become accustomed to these sorts of modeling activities,in accordance to AM’s Active Stakeholder Participation practice, you will find that you need to do lessprodding to get them to participate. Yes, some people are shy at first and may need more prodding than othersbut that’s human nature (given the choice, I prefer to have very outgoing project stakeholders involved withdevelopment efforts as opposed to shy ones that don’t speak their minds).As your team identifies requirements for the current release that you are working on they will often identifyrequirements for future releases, or potential requirements that you may need to implement at some point. Youdon’t want to lose this information, although at the same time you don’t want to invest too much time exploring itnor do you want to invest any time overbuilding your software to fulfill these potential requirements. However,there is some value to your architectural efforts – potential requirements may provide insights into the merits ofone architectural alternative over another. Change cases are a simple technique for documenting potentialrequirements, as you can see in Figure 5 which depicts two change cases for SWA Online. An important partof your scoping effort is to identify both what is currently in scope and what is currently out of scope, and byidentifying a requirement as a change case you are explicitly stating that it is currently out of scope for yourproject efforts. The effective use of change cases as architectural requirements is described in detail in theAgile Architecture article.Figure 5. Two change cases for SWA Online.Change: Expansion into North AmericaLikelihood: Very Likely

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 8 of 133/1/2011Timeframe: 12-18 MonthsImpact:Must support shipments to customers in Canada and Mexico. Relationships with new shippers maybe needed.Relevant taxes and duties would need to be calculated.Product set sold within those markets likely to be different due to legal issues and local preferences.Support for multi-lingual site (English and French are official languages of Canada, Spanish ofMexico)Change: Sale of Virtual Products (online music, video, books, …)Likelihood: Very likelyTimeframe: 6-12 monthsImpact:Must be able to bypass physical shipping processWe may need to support digital licenses for some productsThere may be limits (period of availability, number of copies) on sales of individual itemsSo how much documentation should you write to record your understanding of the project’s scope and initial,high-level requirements? As I suggest in Agile Documentation, just barely enough. In the case of SWAOnline we would likely create an HTML page with the context diagram of Figure 3, the use case diagram ofFigure 4, and a point form list indicating what is in and out of scope. To create the high-level requirementsdocument I would be tempted to have the use case descriptions transcribed into individual word processingdocuments, or perhaps even simple text files, because we’ll want to evolve them as part of our detailedmodeling efforts. Having them as electronic files makes them easy to share and manipulate. As far as theindex cards that we created – the placeholders for business rules, constraints, technical requirements, andchange cases – I would ask my project stakeholders to trust me and to leave them as is because this items willbe evolved during detailed modeling efforts, if we find that we need them at all, and we can deal with them aswe need to at that point. This enables the team to quickly get into detailed modeling efforts, and then intoimplementation, because they have avoided documentation efforts that they may not even need (some of thosebusiness rules may prove inconsequential and therefore any effort invested in documenting them before youknow their true value would be a waste).2. Detailed Requirements Model Storming

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 9 of 133/1/2011Once the scope and high-level requirements for your system have been agreed to, the result of your initialmodeling efforts, you are in a position to define a schedule for your development efforts where you schedule therequirements into iterations. With this plan in place, a plan that evolves over time as your understanding of therequirements evolves, you are now in a position to start actual development.2.1 Starting an IterationAt the beginning of an iteration the various requirements will be spread amongst the developers. On an AgileUP project people volunteer to work, in pairs, on a given use case (or portion thereof), repeating the process ofsigning up for new use cases throughout the iteration until none are left. The first step is to understand whatyour project stakeholders want, in detail, which will likely entail some requirements modeling.There are two basic approaches to modeling that development teams will take at the beginning of an iteration:1. Group modeling of all the requirements for that iteration. With this approach the entire team,including available project stakeholders, work together to explore the detailed requirements, to analyzethose requirements, and to propose changes to the existing system design to support thoserequirements. Assuming your iteration is two-weeks long, my expectation would be that this modelingsession would last from anywhere between one hour and a half day – if your iteration is longer, saybetween four and six weeks, you may decide to invest an entire day in this initial effort. You don’t wantto go any longer than a day with this effort because you are not receiving the concrete feedback that youget when you Prove It With Code. The strengths of this approach is that it builds a concrete vision ofwhat the team is working on for that iteration and how they intend to approach their work and it garnersthe input of all team members and therefore increases the chance of identifying a good initial approach.The weaknesses of this approach is that it only works for small teams, typically of less than ten people,and it wastes time on an individual basis because not everyone will participate on every aspect of themodeling effort. Note that once the initial modeling effort is performed for the iteration that the individualsubteams will still need to model the specific details of what they are working on at appropriate timesthroughout the iteration.2. Individual subteams model their requirement(s). Some development teams will choose to forgo agroup modeling effort at the beginning of an iteration and simply let the individual subteams dive rightinto implementation (see below). This works well when the requirements are not related to one another,or at least not too much, and when developers are following the practice Collective Ownership andworking from a shared code base. The advantage of this approach is that it enables your team to getright into the details on the very first day of the iteration. However, there are several disadvantages.First, when the requirements overlap within sections of your design, perhaps two subteams are workingon something related to calculating the total of an order (e.g. calculation of taxes by one team andcalculation of discounts by another team), then you run the risk of the two subteams doing overlappingwork. This shouldn’t be a serious problem because each subteam should know what the others aredoing and should therefore work together as needed. Second, it takes longer for your team to gel itsimplementation vision for the current iteration. Third, you may initially have contention for access toproject stakeholders because the individual subteams all need input to get started.2.2 During An IterationOnce you’ve gotten over the initial kick-off efforts for an iteration your team quickly falls into a constant effort ofmodel storming, coding, testing, building, and potentially deploying your software. It is during this period thatthe majority of your requirements modeling efforts with your project stakeholders will occur, the goal being toexplore their requirements in detail. Actually, it is more accurate to refer to these efforts simply as modelingsessions because you will very likely iterate through requirements, analysis, and design. These sessions aretypically performed in an impromptu fashion by small groups of people, typically a development subteamworking on a requirement and one or more project stakeholders providing input. Impromptu modeling sessionsare typically sort and often initiated along the lines of a question such as “Sally, do you have a couple ofminutes to explain how customers search for an order item?”

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 10 of 133/1/2011So how would I approach detailed requirements modeling for SWA Online? First, let’s assume that the two ofus are working together as a pair and that our team will be implementing the order definition and placementportions of the basic course of action for the “Place Order” use case in this iteration. We won’t be implementingsearch functionality, any sort of error or exception handling, tax calculations, or discount calculations right now.This example reveals a common problem with use cases – they are often too coarse-grained to schedule into asingle iteration. You are often motivated to either schedule a single use case across multiple iterations,something that is uncomfortable from a project management point of view, or refactor your use case into acollection of smaller ones which is often uncomfortable from a modeling point of view.The basic course of action is often called the “happy path” because everything works in the basic course ofaction – the alternate courses of action describe when things don’t work well, in the case of placing an order thiswould include being out of stock of an item that the customer has requested. However, our goal this iteration isto focus simply on a portion of the happy path for now, the other requirements will be worked on either by othersubteams or perhaps by us at a later date.The first thing that we do is flesh out the logic for the basic course of action, which is presented in Figure 6, andin parallel work on essential (abstract) UI prototypes relevant to this use case. We work on these twoartifacts in parallel because they each approach the problem from a different direction, the use case describeswhat the customer does to place an order and the essential UI prototype specifies what the user interface ofSWA Online must include to support this behavior. Notice how the use case invokes the “Search for Item(s)”use case on line two, consistent with the application of the stereotype in Figure 4. Even thoughthis functionality is invoked in the part of the use case that we’re currently focused on we won’t be implementingthat functionality yet because it’s not in scope. Instead we’ll stub out what we need, perhaps going straight to aresults page listing the theoretical results of our search. Later on in the project the searching functionality willbe added as appropriate, just not now (remember, we’re working incrementally). Also notice how the use casedoesn’t take into consideration any sort of technology issues yet, issues that we may decide to address later.Right now we just want to understand the basic process of placing an order, we can worry aboutimplementation details later (potentially in a few minutes from now). The use case describes logic that we won’tbe implementing this iteration, such as the calculation of taxes and discounts, functionality that we’ll need tostub out when we’re coding.Figure 6. The basic course of action for placing an order.1. The use case begins when a customer chooses to place an order.2. The customer searches for items via the use case “Search for Item(s)”3. The customer selects adds an order item to their order.4. The customer indicates the number of a given item they wish to order.5. The system calculates the subtotal for the item by multiplying the unit price by the number ordered.6. The customer repeats steps 2 through 5 as necessary to build their order.7. The customer finishes adding items to their order.8. The customer provides their ship to and bill to information, including their name, phone number, andsurface address.9. The system calculates the subtotal for the entire order by adding the subtotals of the individual lineitems.

Agile Requirements Modeling Examplehttp://www.agilemodeling.com/essays/agileRequirementsExample.htmPage 11 of 133/1/201110. The system calculates the taxes applicable for the order according to the business rule CalculateTaxes for an Order.11. The system calculates applicable discounts for the order according to the business rule CalculateDiscounts for an Order.12. The system displays the applicable taxes and discounts.13. The system calculates the grand total for the order by adding the applicable taxes to the ordersubtotal and subtracting the discounts.14. The system displays a summary of the order.15. The customer verifies that the order is what they want.16. The system schedules the order for fulfillment (see the use case Fulfill Order).17. The system produces a receipt for the customer summarizing the order.Although we know that we’ll be implementing the UI in a browser we still choose to work with Post It notes andflip chart paper, instead of an HTML editor, because the paper is more flexible and flexibility is what we needright now – as we initially explore the requirements we will be adding UI elements, moving them around, andmoving them very quickly and we want to use a tool that supports this effort. Later on, once the requirementsfor the page(s) have stabilized we’ll switch over to an HTML editor because we’ll want to make our UI moreconcrete for our project stakeholders to evaluate. For now we keep it simple.We are following several of AM’s practices during this effort. We are clearly following the practice CreateSeveral Models in Parallel because we are working on a use case and essential UI prototype, and ModelWith Others because the team is currently comprised of the two of us and as least one project stakeholder thatis providing requirements. We are also following the practice Depict Models Simply. I would also argue thatFigure 6 is a good example of an application of the practice Create Simple Content because it provides justenough details to describe the business logic of the use case. We are also following Apply The Right Artifact(s) – business rules are being captured outside of the use case, although you could argue that the logic forcalculating the grand total of an order is a simple business rule, in a separate business rules artifact (for nowyou would want to create placeholders for Calculate Taxes for an Order and Calculate Discounts for an Order,either sections in a word processing document or as individual index cards). Furthermore user interfacerequirements are being captured in a separate artifact, the essential UI prototype, and if we felt the need “datarequirements” could be captured in a conceptual model (more on this below). We also followed the practiceIterate To Another Artifact, moving back and forth between working on the use case and the essential UIprototype – as we added features to the UI prototype we realized we were missing logic in the use case andvice versa. Finally, we applied the practice Use The Simplest Tools – the UI prototyping was done usingpaper and the use case logic was written on a POW.Assuming that we were satisfied with our modeling efforts, more than likely an effort that took between thirtyand sixty minutes, we would either continue on through analysis and design and finally into implementation orwe would first invest a few minutes to update the project team’s domain model with what we have just learned.I prefer to keep domain models as simple as possible, using CRC cards perhaps, because they are easy towork with and very accessible to project stakeholders. Not only can they be used to show the major entitieswithin your domain but their responsibilities as well, including both data and behavior. Your next best option fordomain modeling is to use a UML class diagram, the advantage is that this diagram can also capture detailsabout the relationships between classes/entities such as multiplicity and roles – relationships between classesare implied by the collaborators with an CRC model. The problem is that class diagrams are not as accessibleto your stakeholders as CRC cards, thus they inhibit active participation, due to their greater complexity.