Agile Software Development ReviewDocument Transcript
Agile Software Development Review
Agile Modeling (AM) is a practice-based methodology for effective modeling and documentation of software-
based systems. At a high level AM is a collection of best practices, depicted in the pattern language map below
(click on the practice for information). At a more detailed level AM is a collection of values, principles, and
practices for modeling software that can be applied on a software development project in an effective and light-
- Acceptance Tests
User Interface Development
A detailed agile SDLC. - Essential Use Cases
- Essential User Interface Prototype
- System Use Cases
- User Interface Flow Diagram
- Usage scenario
- User Interface Prototype
- User Stories
- UML Use Case Diagram
Detailed Structural Modeling Modeling
- External Interface (EI) Specification - Business Rules
- Physical Data Model (PDM) - Conceptual Cases
- UML Class Diagram - Constraints
- UML Object Diagram - Glossary
- Technical Requirements
Dynamic Object Modeling Conceptual Domain Modeling
- UML Communication Diagram
- Class Responsibility Collaborator (CRC) Cards
- UML Composite Structure Diagram
- Logical Data Model (LDM)
- UML Interaction Overview Diagram
- Object Role Model (ORM) Diagram
- UML Sequence Diagram
- Robustness Diagram
- UML State Machine Diagram
- UML Class Diagram
- UML Timing Diagram
Architectural Modeling Process Modeling
- Change Cases
- Data Flow Diagram (DFD)
- Free Form Diagram
- Flow Chart
- Security Threat Modeling
- UML Activity Diagram
- UML Component Diagram
- Value Stream Map
- UML Deployment Diagram
- Workflow diagram Copyright 2003-2005
- UML Package Diagram
Scott W. Ambler
1. Agile Requirements Modeling in a Nutshell
Figure 1 depicts the Agile Model Driven Development (AMDD) lifecycle, which depicts how Agile Modeling
(AM) is applied by agile software development teams. The critical aspects which we're concerned about right
now are initial requirements modeling, iteration modeling, and model storming. The fundamental idea is that
you do just barely enough modeling at the beginning of the project to understand the requirements for your
system at a high level, then you gather the details as you need to on a just-in-time (JIT) basis.
Figure 1. The AMDD lifecycle.
1.1 Initial Requirements Modeling
At the beginning of a project you need to take several days to envision the high-level requirements and to
understand the scope of the release (what you think the system should do). Your goal is to get a gut feel for
what the project is all about, not to document in detail what you think the system should do: the documentation
can come later, if you actually need it. For your initial requirements model my experience is that you need
some form of:
1. Usage model. As the name implies usage models enable you to explore how users will work with your
system. This may be a collection of essential use cases on a Rational Unified Process (RUP) project, a
collection of features for a Feature Driven Development (FDD) project, or a collection of user stories for
an Extreme Programming (XP) project.
2. Initial domain model. A domain model identifies fundamental business entity types and the
relationships between then. Domain models may be depicted as a collection of Class Responsibility
Collaborator (CRC) cards, a slim UML class diagram, or even a slim data model. This domain model
will contain just enough information: the main domain entities, their major attributes, and the
relationships between these entities. Your model doesn’t need to be complete, it just needs to cover
enough information to make you comfortable with the primary domain concepts.
3. User interface model. For user interface intensive projects you should consider developing some
screen sketches or even a user interface prototype.
What level of detail do you actually need? My experience is that you need requirements artifacts which are just
barely good enough to give you this understanding and no more. For example, Figure 2 depicts a simple point-
form use case. This use case could very well have been written on an index card, a piece of flip chart paper, or
on a whiteboard. It contains just enough information for you to understand what the use case does, and in fact it
may contain far too much information for this point in the lifecycle because just the name of the use case might
be enough for your stakeholders to understand the fundamentals of what you mean. Figure 3, on the other hand,
depicts a fully documented formal use case. This is a wonderful example of a well documented use case, but it
goes into far more detail than you possibly need right now. If you actually need this level of detail, and in
practice you rarely do, you can capture it when you actually need to by model storming it at the time. The
longer your project team goes without the concrete feedback of working software, the greater the danger that
you're modeling things that don't reflect what your stakeholders truly need.
The urge to write requirements
documentation should be transformed into
an urge to instead collaborate closely with
your stakeholders and then create working
software based on what they tell you.
Figure 2. A point-form use case.
Name: Enroll in Seminar
Basic Course of Action:
• Student inputs her name and student number
• System verifies the student is eligible to enroll in seminars. If not eligible then the student is informed and use case ends.
• System displays list of available seminars.
• Student chooses a seminar or decides not to enroll at all.
• System validates the student is eligible to enroll in the chosen seminar. If not eligible, the student is asked to choose another.
• System validates the seminar fits into the student’s schedule.
• System calculates and displays fees
• Student verifies the cost and either indicates she wants to enroll or not.
• System enrolls the student in the seminar and bills them for it.
• The system prints enrollment receipt.
Figure 3. A detailed use case.
Name: Enroll in Seminar
Identifier: UC 17
Enroll an existing student in a seminar for which she is eligible.
The Student is registered at the University.
The Student will be enrolled in the course she wants if she is eligible and room is available.
Basic Course of Action:
1. The use case begins when a student wants to enroll in a seminar.
2. The student inputs her name and student number into the system via UI23 Security Login Screen.
3. The system verifies the student is eligible to enroll in seminars at the university according to business rule BR129 Determine
Eligibility to Enroll. [Alt Course A]
4. The system displays UI32 Seminar Selection Screen, which indicates the list of available seminars.
5. The student indicates the seminar in which she wants to enroll. [Alt Course B: The Student Decides Not to Enroll]
6. The system validates the student is eligible to enroll in the seminar according to the business rule BR130 Determine Student
Eligibility to Enroll in a Seminar. [Alt Course C]
7. The system validates the seminar fits into the existing schedule of the student according to the business rule BR143 Validate
Student Seminar Schedule.
8. The system calculates the fees for the seminar based on the fee published in the course catalog, applicable student fees, and
applicable taxes. Apply business rules BR 180 Calculate Student Fees and BR45 Calculate Taxes for Seminar.
9. The system displays the fees via UI33 Display Seminar Fees Screen.
10. The system asks the student if she still wants to enroll in the seminar.
11. The student indicates she wants to enroll in the seminar.
12. The system enrolls the student in the seminar.
13. The system informs the student the enrollment was successful via UI88 Seminar Enrollment Summary Screen.
14. The system bills the student for the seminar, according to business rule BR100 Bill Student for Seminar.
15. The system asks the student if she wants a printed statement of the enrollment.
16. The student indicates she wants a printed statement.
17. The system prints the enrollment statement UI89 Enrollment Summary Report.
18. The use case ends when the student takes the printed statement.
Alternate Course A: The Student is Not Eligible to Enroll in Seminars.
A.3. The registrar determines the student is not eligible to enroll in seminars.
A.4. The registrar informs the student he is not eligible to enroll.
A.5. The use case ends.
Alternate Course B: The Student Decides Not to Enroll in an Available Seminar
B.5. The student views the list of seminars and does not see one in which he wants to enroll.
B.6. The use case ends.
Alternate Course C: The Student Does Not Have the Prerequisites
C.6. The registrar determines the student is not eligible to enroll in the seminar he chose.
C.7. The registrar informs the student he does not have the prerequisites.
C.8. The registrar informs the student of the prerequisites he needs.
C.9. The use case continues at Step 4 in the basic course of action.
Because there are several different types of requirements, some or all of which may be applicable to your
project, and because each modeling artifact has it’s strengths and weaknesses, you will want to have several
requirements modeling artifacts in your intellectual toolkit to be effective. Table 1 summarizes common
artifacts for modeling requirements, artifacts that are described in greater detail in the article Artifacts for Agile
Modeling. The type(s) of requirement that the artifact is typically used to model is indicated as well as a
potential “simple” tool that you can use to create the artifact (the importance of using simple tools was
discussed earlier in the section Some Philosophy).
Table 1. Candidate artifacts for modeling requirements.
Artifact Type Simple Tool Description
Acceptance Either FITNesse Describes an observable feature of a system which is of interest
Test to one or more project stakeholders.
Business rule Behavioral Index card A business rule is an operating principle or policy that
definition your software must satisfy.
Change case Either Index card Change cases are used to describe new potential
requirements for a system or modifications to existing
CRC model Either, Usually Index cards A Class Responsibility Collaborator (CRC) model is a
Behavioral collection of standard index cards, each of which have
been divided into three sections, indicating the name of
the class, the responsibilities of the class, and the
collaborators of the class. A class represents a collection
of similar objects, a responsibility is something that a
class knows or does, and a collaborator is another class
that a class interacts with to fulfill its responsibilities. CRC
models are used, during requirements modeling, for
conceptual modeling which explores domain concepts
and high-level relationships between them.
Constraint Either Index card A constraint is a restriction on the degree of freedom you
definition have in providing a solution. Constraints are effectively
global requirements for your project.
Data flow Behavioral Whiteboard A data-flow diagram (DFD) shows the movement of data
diagram drawing within a system between processes, entities, and data
stores. When modeling requirements a DFD can be used
(DFD) to model the context of your system, indicating the major
external entities that your system interacts with.
Essential UI Either Post It notes and An essential user interface (UI) prototype is a low-fidelity
prototype flip chart paper model, or prototype, of the UI for your system – it
represents the general ideas behind the UI but not the
Essential use Behavioral Paper A use case is a sequence of actions that provide a
case measurable value to an actor. An essential use-case is a
simplified, abstract, generalized use case that captures
the intentions of a user in a technology and
implementation independent manner.
Feature Either, Usually Index card A feature is a “small, useful result in the eyes of the
Behavioral client”. A feature is a tiny building block for planning,
reporting, and tracking. It’s understandable, measurable,
and do-able (along with several other features) within a
two-week increment (Palmer & Felsing 2002).
Technical Non-Behavioral Index card A technical requirement pertains to a non-functional
requirement aspect of your system, such as a performance-related
issue, a reliability issue, or technical environment issue.
Usage Behavioral Index card A usage scenario describes a single path of logic through
scenario one or more use cases or user stories. A use-case
scenario could represent the basic course of action, the
happy path, through a single use case, a combination of
portions of the happy path replaced by the steps of one or
more alternate paths through a single use case, or a path
spanning several use cases or user stories.
Use case Behavioral Whiteboard sketch The use-case diagram depicts a collection of use cases,
diagram actors, their associations, and optionally a system
boundary box. When modeling requirements a use case
diagram can be used to model the context of your system,
indicating the major external entities that your system
User story Either Index card A user story is a reminder to have a conversation with
your project stakeholders. User stories capture high-level
requirements, including behavioral requirements,
business rules, constraints, and technical requirements.
An important thing to remember is that although there are several artifacts that you can potentially use for
requirements gathering that doesn’t mean that you need to use all of them on any given project. You should
understand when it is appropriate to use each artifact, knowledge that enables you to follow the practice Apply
The Right Artifact(s) to your situation at hand.
The underlying process often motivates artifact choice. On the home page I indicate that AM is used in
conjunction with another software process, such as eXtreme Programming (XP) or the Unified Process (UP),
whose scope is the full lifecycle. Very often the underlying process will prefer certain primary requirements
artifact(s), in the case of XP user stories and for the UP use cases, an issue that you must consider when
requirements modeling. See the articles AM and XP and AM and UP for further details.
Some Potential Analysis Models
Are the artifacts created taking an agile approach to analysis any different than the ones created as the result of
traditional analysis? In a way they are. They are in fact the same types of artifacts, a use case diagram is a use
case diagram after all, but the way in which they are created are different. The artifacts are created following
the principles and practices of AM, they are just barely good enough and are often discarded so as to travel
Table 1 lists common artifacts used during analysis modeling and suggests a simple tool with which you could
create such an artifact. It is interesting to note that this list is meant to be representative, a more thorough list is
presented in the article Artifacts for Agile Modeling and in the book Agile Modeling.
Table 1. Candidate artifacts for analysis modeling.
Artifact Simple Tool Description
Activity Diagram Whiteboard UML activity diagrams are used during analysis modeling to explore the logic of a usage
scenario (see below), system use case, or the flow of logic of a business process. In many
ways activity diagrams are the object-oriented equivalent of flow charts and data-flow
Class Diagram Whiteboard Class diagrams show the classes of the system, their inter-relationships (including
inheritance, aggregation, and association), and the operations and attributes of the classes.
During analysis you can use class diagrams to represent your conceptual model which
depict your detailed understanding of the problem space for your system.
Constraint Index card A constraint is a restriction on the degree of freedom you have in providing a solution.
definition Constraints are effectively global requirements for your project.
CRC model Index cards A Class Responsibility Collaborator (CRC) model is a collection of standard index cards,
each of which have been divided into three sections, indicating the name of the class, the
responsibilities of the class, and the collaborators of the class. Like class diagrams, CRC
models are used during analysis modeling for conceptual modeling.
Data flow diagram Whiteboard A data-flow diagram (DFD) shows the movement of data within a system between
(DFD) processes, entities, and data stores. When analysis modeling a DFD can be used to model
the existing and/or proposed business processes that your system will support.
Entity/Relationship Whiteboard E/R diagrams show the main entities, their data attributes, and the relationships between
(E/R) diagram those entities. Like class diagrams E/R diagrams can be used for conceptual modeling, in
many ways E/R diagrams can be thought of as a subset of class diagrams.
Flow chart Whiteboard Flow charts are used in a similar manner to activity diagrams.
Robustness Whiteboard Robustness diagrams can be used to analyze usage scenarios to identify candidate classes
diagrams and major user interface elements (screens, reports, ...).
Sequence diagram Whiteboard Sequence diagrams are used to model the logic of usage scenarios. Sequence diagrams
model the flow of logic within your system in a visual manner, enabling you to both
explore and validate your logic.
State chart diagram Whiteboard State chart diagrams depict the various states, and the transitions between those states, that
an entity exhibits. During analysis modeling state chart diagrams are used to explore the
lifecycle of an entity that exhibits complex behavior.
System use case Paper A use case is a sequence of actions that provide a measurable value to an actor. A system
use case includes high-level implementation decisions in it. For example, a system use
case will refer to specific user interface components – such as screens, HTML pages, or
reports. System use cases will also reflect fundamental architectural decisions, such as the
use of ATMs versus cell phones to access your bank account.
UI prototype Whiteboard A user interface (UI) prototype models the user interface of your system. As a part of
analysis modeling it enables you to explore the problem space that your system addresses
in a manner that your project stakeholders understand. Remember, the user interface is the
system to most people.
Usage scenario Index card A usage scenario is exactly what its name indicates – the description of a potential way that
your system is used.
Use case diagram Whiteboard The use-case diagram depicts a collection of use cases, actors, their associations, and
optionally a system boundary box. When analysis modeling a use case diagram can be
used to depict the business functionality, at a high-level, that your system will support. It
can also be used to depict the scope of the various releases of your system via the use of
color or system boundary boxes.
Design Throughout The Lifecycle
Figure 1 depicts the generic agile software development lifecycle. For the sake of discussion, the important
thing to note is that there is no design phase, nor a requirements phase for that matter, which traditionalists are
familiar with. Agile developers will do some high-level architectural modeling during Iteration 0, also known
as the warm-up phase, and detailed design during development iterations and even during the end game (if
Figure 1. The Agile SDLC.
Architecture provides the foundation from which systems are built and an architectural model defines the vision
on which your architecture is based. The scope of architecture can be that of a single application, of a family of
applications, for an organization, or for an infrastructure such as the Internet that is shared by many
organizations. Regardless of the scope, my experience is that you can take an agile approach to the modeling,
development, and evolution of an architecture.
1. Every system has an architecture. BUT, it may not necessarily have architectural models describing that
architecture. For example, a small team taking the XP approach that is working together in the same room may
not find any need to model their system architecture because everyone on the team knows it well enough that
having a model doesn’t provide sufficient value to them. Or, if an architectural model exists it will often be a
few simple plain old whiteboard (POW) sketches potentially backed by a defined project metaphor. This works
because the communication aspects of XP, including pair programming and Collective Ownership, negate the
need for architecture model(s) that need to be developed and maintained throughout the project. Other teams
– teams not following XP, larger teams, teams where people are not co-located – will find that the greater
communication challenges inherent in their environment requires them to go beyond word-of-mouth
architecture. These teams will choose to create architectural models to provide guidance to developers as to
how they should build their software. Fundamentally, the reason why you perform architectural modeling is to
address the risk of members of your development team not working to a common vision.
2. Architecture scales agile. This is true of traditional techniques as well. Have a viable and accepted
architecture strategy for a project is absolutely critical to your success, particularly in the complex
situations which agile teams find themselves in at scale. Scaling issues include team size, regulatory
compliance, distributed teams, system complexity, and so on. An effective approach to architecture
enables you to address these scaling issues.
2. Architecture Throughout the Lifecycle
The reality is that the development of architecture is very hard, an effort that is key to your success, and one
that you’re not going to get right from the start. An iterative and incremental approach addresses the risk of an
inadequate or inappropriate architecture by developing it a bit at a time, and only when you need it.
There are four basic strategies for organizing agile teams at scale:
1. Architecture-driven approach. With this strategy you organize your subteams around the subsystems/
components called out in your architecture. This strategy works well when your architecture is of high
quality (it's loosely coupled and highly cohesive) and the interfaces to the subsystems have been
identified before the subteams really get going (the interfaces will evolve over time, but you want to get
a good start at them initially). The challenge with this strategy is that it requires your requirements to be
captured in a way which reflects the architecture. For example, if your architecture is based on large-
scale business domain components then a requirement should strive to focus on a single business
domain if possible. If your architecture is based on technical tiers -- such as a 3-tier architecture with
user interface (UI), business, and data tiers -- then requirements should focus on a single tier if possible.
2. Feature-driven approach. With this strategy each subteam implements a feature at a time, a feature
being a meaningful chunk of functionality to your stakeholders. I would apply this strategy in situation
where the architecture exhibits a lot of coupling AND where you have sophisticated development
practices in place. The challenge with this approach is that the subteams often need to access a wide
range of the source code to implement the feature and thereby run the risk of collisions with other
subteams. As a result these teams sophisticated change management, continuous integration, and
potentially even parallel independent testing strategies in place (to name a few).
3. Open source approach. With this strategy one or more subsystems/components are developed in an
open source manner, even if it is for a single organization (this is called internal open source). This
strategy is typically used for subsystems/components which are extensively reused by many teams, for
example a security framework, and which must evolve quickly to meet the changing needs of the other
systems accessing/using them. This strategy requires you to adopt tools and processes which support
open source approaches.
4. Combinations thereof. Most agile teams at scale will combine the previous three strategies as
6. The Agile Architecture Process
Figure 3 depicts the process for architecture activities on an agile project. The core architecture team is
responsible for envisioning the initial architecture then bringing it to the rest of the project team for feedback
and subsequent evolution. To avoid an ivory tower architecture the members of the core architecture team will
take active roles on the various subteams on the project, communicating the architecture to the subteams and
working with them to prove portions of the architecture via concrete experiments. From the point of view of the
development subteams the architects act as consultants whose expertise is the corporate architecture as well as
active members of the subteam. The core architecture team should view the development subteams as their
customers, as project stakeholders for their architecture, customers that will need help from them and who will
have new requirements that necessitate change to the architecture. In short, the core architecture team should
actively work with their project stakeholders, in this case the development subteams.
Figure 3. Agile architecture process.
The core architecture team will find that they need to get together occasionally to evolve the architecture as the
project progresses, negotiating changes to the architecture and updating their architectural model(s), if any, as
appropriate. These meetings will be frequent at the beginning of a project and will be needed less and less as
the architecture solidifies. It will be common for members of the development subteams, who may not be
members of the core architecture team, to attend some meetings to present information, perhaps they were
involved with some technical prototyping and have findings to share with the architects. The best meetings are
short, often no more than half an hour in length, and are often held standing up around a whiteboard – everyone
should come prepared to the meetings, willing to present and discuss their issues as well as to work together as
a team to quickly come to resolutions.
7. Requirements-Driven Architecture
Your architecture must be based on requirements otherwise you are hacking, it’s as simple as that. The practice
Active Stakeholder Participation is critical to your success when it comes to identifying architectural
requirements – remember, requirements come from project stakeholders, not developers. Good sources for
technical architecture requirements will include your users and their direct management as they will often have
some insight into technical requirements and constraints. Operations staff will definitely have requirements for
you pertaining to your deployment architecture. The best sources for business-oriented requirements are
exactly who you would expect – your users, their managers. Senior management within your organization will
have insights that may lead to potential change cases for your system.
As you would expect the practices Apply The Right Artifact(s) and Create Several Models in Parallel apply to
your architectural requirements effort. When you are working on the technical aspects of your architecture you
will want to base it on technical requirements, constraints, and possibly change cases. Similarly, when you are
working on business aspects of your architecture, potentially identifying software subsystems or business
components, you will likely need to focus on essential use cases or user stories that describe critical usage
requirements and potentially the key business rules applicable to your system.
A common mistake that architecture teams (or for smaller projects the architecture owner) will make is to
ignore existing and pertinent artifacts, such as network or deployment diagrams that describe your organizations
existing technical infrastructure, enterprise-level business models (use case models, process diagrams, workflow
diagrams, corporate business rules, and so on), or corporate deployment standards (for workstations, branch
offices, etc.) that your system is expected to conform to. Yes, the existing artifacts may be out of date or simply
not apply to your effort, but you should at least make an effort to examine them and take advantage of the
existing work wherever possible. A little bit of reading or discussion with the right people is likely to save you
significant effort later on. In other words, don’t forget to reuse existing artifacts whenever possible.
An important concept to understand about architectural modeling is that although it typically occurs early in
your project it never occurs first. Fundamentally, you will always invest time identifying some requirements
first. Anything else is hacking, and hacking certainly isn’t agile.
13. Take a Multi-View Approach
Agile Modeling's Multiple Models principle advises you to recognize that because modern systems are complex
that you will need to consider a range of views in your architecture. Although they take different approaches, a
multi-view strategy is a fundamental concept in modern architectural frameworks such as the Zachman
Framework, TOGAF, 4+1, and so on. Each of these frameworks have very good reasons for their choice of
views, they all seem to work well in practice, they can all be approached in an agile manner, so my advice is to
review your options and pick the architectural framework which best reflects the culture of your organization.
My goal here isn't to propose yet another architecture framework, it is to make you aware of them and their
underlying concepts. Figure 4 overviews the views and concerns which software/system architects need to be
Figure 4. Architectural views and concerns.
14. How Does This Work?
The architectural approach that I’ve described is markedly different that what a lot of organizations are
currently doing today. Table 1 compares and contrasts the architectural practices that are commonly found in
many organizations with their agile counterparts. Clearly, there’s a big difference. The agile approach works
because of its focus on people working together effectively as a team. Agile Modeling recognizes that people
are fallible, that they aren’t likely to get the architecture right to begin with and therefore need the opportunity
for acting on feedback from implementation efforts. When agile architects are productive members of the
development team, and when the development team has been involved with the architectural efforts to begin
with, then comprehensive documentation isn’t needed by them, the navigation diagrams are sufficient (granted,
when this is not the case documentation, hopefully minimal, may be required). Architecture reviews aren’t
needed because the architecture is being proved through the concrete feedback of architectural
prototyping/spikes and because people can see the architecture evolve because your models are displayed
publicly for everyone to see. Agile architects have the courage to focus on solving today’s problem today and
trusting that they can solve tomorrow’s problem tomorrow (Beck, 2000), and the humility to recognize that they
cannot accurately predict the future and therefore choose not to overbuild their architectures.
Table 1. Comparing Common and Agile Architectural Practices.
Common Practice Agile Practice
Architects are held in high esteem and are often placed, or even Agile architects have the humility to admit that they don’t walk on
worse place themselves, on pedestals water
Agile architects are active members of development teams,
Architects are too busy to get their hands dirty with
developing software where appropriate and acting as architectural
consultants to the team
Agile architects have the humility to admit that they can’t predict
Architecture models are robust to enable them to fulfill future
the future and instead have the courage to trust they can solve
tomorrow’s problem tomorrow
The goal is to develop a comprehensive architecture early in a You evolve your architecture incrementally and iteratively,
project allowing it to emerge over time
Travel light and focus on navigation diagrams that overview your
Well-documented architecture model(s) are required architecture, documenting just enough to communicate to your
Architecture model(s) are communicated only when they are Architecture model(s) are displayed publicly, even when they are
“suitable for public consumption” a work in progress, to promote feedback from others
Architecture reviews are held to validate your model(s) before
Architectures are proved through concrete experiments
being put into use
Model Type Simple Paper Whiteboard Software
Acceptance Test FITNesse
Business Rule Card Word Processor
Change Case X Card Word Processor
Class Responsibility Collaborator (CRC) model X Card
Constraint Card Word Processor
Contract model As Needed
Data Flow Diagram (DFD) X CASE
Domain Model X CASE
Essential/Abstract Use Case X Flip chart X Word Processor
Essential/Abstract User Interface Prototype X Flip chart
Feature X Card Spreadsheet
Free-Form Diagrams X X Diagramming Tool
Flow Chart X
Glossary Card Word Processor
Logical Data Model (LDM) CASE
Network Diagram Diagramming
Object Role Model (ORM) Diagram X
Personas X Flip chart Word Processor
Physical Data Model (PDM) CASE
Robustness Diagram X
Security Threat Model X
System Use Case Word Processor
Technical Requirement Card Word Processor
UML 2 Activity Diagram X CASE
UML 2 Class Diagram X CASE
UML 2 Communication/Collaboration Diagram X
UML 2 Component Diagram X CASE
UML 2 Composite Structure Diagram X
UML 2 Deployment Diagram X CASE
UML 2 Interaction Overview Diagram X
UML 2 Object Diagram X
UML 2 Package Diagram X CASE
UML 2 Sequence Diagram X CASE
UML 2 State Machine Diagram X CASE
UML 2 Timing Diagram X CASE
UML 2 Use Case Diagram X CASE
Usage Scenario X Card Word Processor
User Interface Flow Diagram (Storyboard) X Diagramming
Prototyping tool or
User Interface Prototype X
User Story X Card Spreadsheet
Value Stream Map X
Maximize stakeholder investment
Fulfill a purpose
Describe information that is less likely to change
Describe “good things to know”
Have a specific customer and facilitate the work efforts of that customer
Are sufficiently accurate, consistent, and detailed
Are sufficiently indexed
Valid reasons to document:
Your project stakeholders require it
To define a contract model
To support communication with an external group
To think something through