A series of posts providing proven guidance for developing ASP.NET MVC applications from idea to well-designed implementation.
Part I - Planning & Design
For the planning and design phase of project delivery, each "day" will have an objective, inputs, activities, and outputs:
- Objective: This is a short description of the goal – or expected end result – of the day.
- Inputs: These are the informational inputs, document artifacts, and decisions that should have been made before beginning the day’s activities.
- Activities: This is the core element of each day, describing the interactions with the client and the practices used for ultimately transforming ideas into production code. For each day, we’ll discuss the activities to be achieved and put them into practice on our example project.
- Outputs: These are the artifacts that will have been generated during the day’s activities, some of which may be used as inputs for subsequent days.
Day 1 – Define the Requirements & Actor/System Interactions
Objective of the Day
Work with the client to translate ideas into requirements. By the end of the day, you should be able to concisely describe the project’s vision, actors, and implementable requirements.
Inputs
- Client project ideas, with knowledge of who will be interacting with the system.
Activities
Project Vision
The first activity of the day is to establish the project vision. The vision describes the high-level goals of the system and the business case for implementation. It’s the two-minute elevator speech describing what the system is intended to achieve.
While defining the project vision, a key activity will also be to clearly define the “actors,” or the people who interact with the system and the goal(s) of those interactions, accordingly.
This may seem like a simple, or even dismissible, step, but clearly defining the vision and actors is one of the most essential elements of the entire project. The vision serves as a good litmus test to use to verify if a client idea is relevant to the project’s vision. Additionally, by clearly defining the actors, it allows you and the client to focus on just those requirements which satisfy the needs of those actors; i.e., if an idea comes up which doesn’t serve the needs of one of the defined actors, it can be summarily discarded or put on an “idea parking lot” (so the client feels like you’re actually going to look at it again someday…which you’re not). In other words, don’t skip this!
Putting it into Practice
Our aspiring client’s company is Acme Telecom. Acme Telecom would like to create a support call tracking system to log and monitor all calls, which will be tracked as “support tickets,” coming into its support department. Currently, Acme Telecom’s paper-based system is making it difficult to assess how well its support staff is responding and closing calls. Acme Telecom doesn’t want to try to do too much at once, so the client wants to keep things very simple and small for this first release. Accordingly, the vision that we and the client were able to agree on was as follows:
Acme Telecom’s paper-based approach to support call tracking is limiting the company’s ability to improve support capabilities. Accordingly, Acme Telecom needs an easy-to-use, secure, web-based Call & Logging System (or "CLogS" for short) for its Support Staff to track and resolve support calls from Customers as “support tickets.” In addition to facilitating support ticket resolution, the system must provide high-level reporting for Management to filter support ticket logs and to assess key performance metrics, such as rate of resolution and resolution bottlenecks.
Not only does this vision define the general scope of the project, but did you notice that the actors were also clearly stated? (We can even infer hints of the domain model…but that’ll be for a later discussion.)
Taking the vision a bit further, the actors, and goals of each actor, are as follows:
| Actor | Major Goals |
|---|---|
| Support Staff | Log support ticket. Update and/or resolve calls opened by self. |
| Customer | Have support staff resolve calls. |
| Management | Run filterable reports on call logs. Run "canned reports" to assess resolution performance. |
With that, we have a good general scope definition of the project, we know who the primary stakeholders are, and what each would like to achieve.
At this stage, it doesn’t look like the customer would actually be interacting with the system since they’ll be calling the Support Staff directly...should we include them as an actor? Yes, due to the fact that they represent the key stakeholder to be satisfied and should be considered during requirements elaboration by asking “Is this idea going to help the Customer get their calls resolved?”
User Stories or Use Cases?
Both User Stories and Use Cases summarize the various features of the system. Each should be small enough to be estimable, but big enough that the client would be willing to pay for its implementation and measure progress. With that said, it is important to decide, very early on, if requirements will be defined using User Stories or Use Cases (or another means altogether) as there are appreciable differences between the two.
Users Stories, an element of the Scrum/XP, are very short requirement descriptions which are intended to be elaborated during development iterations; they are truly markers for further discussion. A User Story is a feature stated from the perspective of the actor(s) who will benefit from that feature. Each User Story typically includes the following details:
- Description: The feature from the actor’s perspective.
- Priority: Higher priority features should be addressed earlier in the project life-cycle while lower priority features may be dropped in favor of higher priority change requests, or dropped altogether to assist with meeting schedule deadlines.
- Risk: Higher risk User Stories may be A) split into smaller risk User Stories, B) researched to mitigate risk, C) reflected as a higher uncertainty in the estimate, or D) dropped to reduce uncertainty in scope and schedule.
- Estimate: Typically described in “points” rather than in hours to better facilitate relative-estimating techniques.
To learn more about User Stories, I encourage you to read User Stories Applied by Mike Cohn.
Use Cases, on the other hand, include much more detail for each requirement. For example, while a User Story may be described in a sentence or two, a Use Case describes prerequisites for the Use Case to be activated, a “happy path” of execution, exceptive cases to execution, and post-conditions, describing the state of the system after completion. To learn more about Use Cases, I encourage you to read Applying Use Cases by Geri Schneider.
There are pros and cons to each; google “User Story vs. Use Case” to get a swath of opinions. Personally, I prefer User Stories if I feel the client is very unsure of what the final system will be, or if the client is supportive of flexible scope; I prefer Use Cases if the end result is very definable or if the client demands fixed bid (which always makes me shudder). There’s more to it than that, but for the purposes at hand, we’re going to go with User Stories for Acme Telecom’s CLogS application.
Putting it into Practice
Now that the vision, actors, and actor-goals have been defined, we’re ready to define the requirements of the solution. We’ll do so by working with the client to define the requirements as User Stories. To keep things simple, we’ll ignore Priority, Risk and Estimate, focusing simply on the description of each. Our User Stories for CLogS are as follows:
- Support Staff may open a new support ticket and provide details including: Customer, Issue Details (such as description and “dynamically managed” type), Status, and Resolution Details (if resolved immediately). Status of the call may be New, In Progress, or Resolved. (“Dynamically managed” means that if the issue type isn’t available, the Support Staff may enter a new one when entering the support ticket.)
- Support Staff may manage Customer details, adding and updating Customer information when necessary.
- Support Staff may view listing of all tickets opened by self, defaulting to those which are not resolved and filter the listing, accordingly.
- Support Staff may search for an existing support ticket, opened by self, view details of ticket, and update its status and resolution details.
- Management may view listing of all tickets, defaulting to those which are not resolved and filter the listing, accordingly.
- Management may view report showing information regarding how quickly calls are being resolved, called the “Ticket Resolution Report by Support Staff.” The report may be run for all Support Staff or for a specific Support Staff employee. The manager creating the report may only include Support Staff of whom they are manager.
- Admin may view the “Ticket Resolution Report by Support Staff” for any and all Support Staff.
- Management may view chart showing a breakdown of call by issue type and average resolution time for each issue type, called the “Ticket Resolution Report by Issue Type.” The manager creating the report will only see stats for Support Staff of whom they are manager.
- Admin may view the “Ticket Resolution Report by Issue Type” to include any and all Support Staff.
- Admin may manage all details of Support Staff and Management, along with which Support Staff are assigned to which Manager. Each Support Staff may only have, and must have, one Manager.
Data Dictionary
One of the most frequently skipped steps of project delivery is also one of the simplest and helpful: the creation of a data dictionary. A data dictionary is a simple glossary of domain-related terms which serves to reduce requirements confusion between the client and project delivery team.
As project requirements become more complicated, a data dictionary becomes increasingly important to ensure everyone is speaking the same language. (Not) surprisingly, it’s frequently difficult for even client associates to agree upon term definitions; a data dictionary helps to get people talking and to (hopefully) agree upon the meaning of business terms. Forming this agreement of definitions forms the basis of Ubiquitous Language, a prominent component of Domain-Driven Design.
A few years back I developed a project management tool for a construction management project. One of the key features of this tool was a Master Budget Report which combined information from various sources to ultimately provide an Estimate at Completion for each project. The report’s data columns included Expenditures, Change Orders, Pending Obligations, Remaining Obligations, Total Obligations, and others. It took over three months of workshops involving client stakeholders from the financial group, project controls group, project managers, and upper management to agree upon what constituted a Pending Obligation vs. a Remaining Obligation and to sort out other such definitions and equations associated with the report. Imagine the frustrations that would have ensued if we had tried to develop this “standard” report when no one agreed to what was actually “standard.”
The lesson of the story is...don’t underestimate the usefulness of a well-discussed data dictionary. And knowing is half the battle.
Putting it into Practice
Acme Telecom’s CLogS is starting to take shape as vaporware; we’ve agreed to the vision and even the requirements. But during requirement elaboration discussions, there was some confusion on a few key terms. The following data dictionary helped to alleviate the confusion:
| Term | Definition |
|---|---|
| Customer | A person who has an Acme Telecom account number. (Anyone else is just an annoying person wasting Support Staff’s time.) |
| Resolution Time | The number of business days (whole number) to resolve a call is calculated by taking the difference between the day a ticket is opened, and the day when it is resolved, excluding weekends. If a ticket is resolved in the same day it was opened, its resolution time is 0 days. |
| Avg. Resolution Time | This is the number of mean business days (decimal number) it takes for an arbitrary group of support tickets to be resolved; i.e., the sum of business days to resolve each ticket divided by the number of tickets. |
It was easy to assume that everyone understood what "resolution time" meant when discussing requirements. But as we attempted to define this term in the data dictionary, it was recognized to be a non-trivial idea. Having this cleared up will help to ensure that anyone using the system has the same understanding of the term...assuming they’ve taken five minutes to read the data dictionary, which is quite an assumption in and of itself!
It should also be noted that the data dictionary was used to not only clarify project-related terms and calculations, but also to clarify the definition of actors.
While it’s not necessary to document every project term, any term which involves tricky calculations, subjectivity in defining, or has been identified as causing disagreement, should certainly be included. Furthermore, the data dictionary may be separated into separate lists such as Actors, Domain, and Calculations, but start simple and expand when necessary.
Actor/System Interaction Diagrams
I’ve been a strong proponent of agile development techniques for years; but a challenge I’ve always had is keeping track of the "big picture" as requirements are broken down into more granular requirements as user stories. An associate of mine, Jim Tucker, introduced me to a quick and easy technique that I’ve not seen surpassed for expressing the big picture in a clear and concise manner.
Before delving into technical design, Jim creates "Actor / System Interaction Diagrams" (as UML sequence diagrams) to document how the actors interact with each other and with the underlying system, treating the system as a black box. It’s possible to use this technique not only for the overall system, but down to the level of a single user story. This facilitates "zooming in and out" of the details as appropriate.
This is similar in nature to the back and forth between an actor’s actions and system’s responses described within a Use Case (an alternative approach to User Stories for documenting feature requirements), and to Craig Larman’s System Sequence Diagrams in Applying UML and Design Patterns. It differs from Use Cases in the fact that it’s more graphically oriented, and differs from both in that it may be easily expanded to include many participants and need not be constrained to a single feature. On a recent project, we used this technique to illustrate the high-level interactions among eight actors and multiple third party systems; the end result was simple enough for the client to understand and verify its logic, but expressive enough to be a useful artifact during technical design.
To use this approach, it’s first necessary to understand UML sequence diagrams, which is beyond the scope of this article. (Googling "UML sequence diagrams" will get you going in the right direction.) Having an understanding of sequence diagrams, Actor / System Interaction Diagrams differ from sequence diagrams in the following ways:
- Actors are used in place of classes.
- The system itself is treated as a single participant in the sequence diagram.
- The "messages" among participants, instead of being API calls, are requests between actors and/or the system itself.
But, as usual, an example speaks a thousand words...
Putting it into Practice
The trickiest User Story in the CLogS application is as follows:
Support Staff may open a new support ticket and provide details including: Customer, Issue Details (such as description and type), Status, and Resolution Details (if resolved immediately). Status of the call may be New, In Progress, or Resolved.
This one caused the most discussion and had the most unknowns. Accordingly, it was decided that an Actor / System Interaction Diagram would be created to clarify the sequence of interactions.
The actors that will be in the sequence diagram include Customer, Support Staff, and the CLogS application. The sequence of events to handle a new support call is as follows:
- Customer calls Support Staff and describes the issue.
- Support Staff opens a new support ticket in CLogS which requires the following sub-steps:
- Support Staff gets Customer account number.
- Support Staff uses account number to find customer.
- If not found, Support Staff adds a new Customer entry.
- If found (or after created), Support Staff generates a new support ticket for the Customer.
- Support Staff adds issue details to the new support ticket entry.
- Support Staff gets Customer account number.
- If resolvable, Support Staff assists the Customer and marks the support ticket as resolved.
- Otherwise, Support Staff gives the Customer the support ticket reference number and pinky swears to resolve the issue and get back with them.
The Actor / System Interaction Diagram above shows the actors involved and their interactions with each other. Although this level of detail isn’t necessary for every User Story, it’s a useful technique for illustrating the business processes behind more complex User Stories. Furthermore, this technique need not be limited to the User Story level; alternatively, you could create Actor / System Interaction Diagrams for major modules and/or include third party systems as additional "actors." UML sequence diagrams are quite versatile for this kind of work.
Outputs
- Project Vision
- User Stories or Use Cases
- Data Dictionary
- Actor / System Interaction Diagrams
That wraps up Day 1 in this series. In Day 2, we'll Define the Domain Conceptual Model...
Enjoy!
Billy McCafferty
DIGITAL JUICE
No comments:
Post a Comment
Thank's!