While it isn't usually part of the software architect's job to write a requirements specification, it does often fall to you to ensure that it has been properly written. And, because the requirements specification will be your main source of information about the application, you're likely to have a vested interest in its overall utility. In this third article in my series on designing software architectures, I'll show you how to write a solid and usable requirements specification, a process that starts with requirements analysis and ends with a series of well-documented use cases.
In a typical Rational Unified Process®, or RUP®, cycle, requirements analysis begins in the inception phase, when most requirements are gathered. At this point the requirements will not be final, as more will come along as the application develops, especially during the elaboration phase. Requirements analysis starts with the development team analysts and the client going over the scope of the application together. The requirements that come out of this process are then documented using a formalized method. In RUP, use cases are typically used to understand and document the application's functional requirements. Quality requirements are documented elsewhere and will be discussed in a later column in this series.
This month I'll cover all the essential elements of the requirements specification and then take a closer look at the development and documentation of use cases.
Most software companies use some sort of template for documenting the progress and outcome of development projects. While the template is very helpful, it can also be a liability if not occasionally reconsidered and revised. It is important to be sure that the template, which is a generalized document, is sufficient to the particulars of a given project. It is also important that it contain certain elements, without which it would be incomplete.
As the project architect it might fall to you to study and revise the documentation template. To assist you in this, let's first look at the things you should expect to find in your generalized requirements specification, which should therefore be outlined in the template. An ideal requirements specification includes the following information (in one or more documents):
- Introduction to the system and its specifications
- Listing of functional requirements:
- System-level use case diagrams
- Use case documentation
- Quality requirements or other requirements:
- Usability
- Reliability
- Performance
- Supportability
In this article, I'll focus on the specification of functional requirements, which can be aptly described with use cases.
Most use cases are first developed as a kind of story and then diagramed in UML, or the Unified Modeling Language. In this section, I'll show a very simple Web store application example to introduce use case diagramming with UML. In UML, a use case is drawn as an ellipse with its name inside. Figure 1 shows three use cases and a box indicating the system boundaries.
Figure 1. Three use cases
The next step is to show the interactions between actors and the application for the given use case. An actor is a person or system outside of your application that will interact with it. The actor is drawn as a stick figure, as seen in Figure 2.
Figure 2. An actor
In Figure 3 you can see how inheritance is diagrammed in a use case. The Customer Representative is inherited from the Customer.
Figure 3. Diagramming inheritance
After you've established the basics -- the three use cases, the actors involved, and the inheritance between them -- you can begin modeling their interactions within the application, or with the actual use cases. I've already established three use cases and two actors. The use cases are Login, Browse Catalog, and Place Order. The actors are Customer and Customer Representative. In Figure 4, I've gone one step further and modeled the relationship of each actor to each of my use cases. In so doing, I've added a fourth use case to my collection.
Figure 4. A use case diagram of the example
As you can see, the Customer and Customer Representative both interact with the three original use cases (Login, Browse Catalog, and Place Order), but the Customer Representative has, in addition, a use case of its own: Run Sales Report.
You might choose to use one or several use case diagrams to model your system. For more complex systems it is a good idea to draw several rather than attempting to contain too much information in a single diagram. Putting everything into one diagram can make the diagram difficult to read.
In addition to diagramming your use case, it is important to document it. Every use case should be documented in either its own document or at least in its own section of the specification. The following list is comprehensive, so not every use case need contain every element below; but you should think carefully before leaving something out.
- Name: A brief, descriptive, and unique name for the use case.
- Description: A short description of what the use case does.
- Actors: A list of all the actors that interact with the use case.
- Priority: A short description of how important the use case
is in the overall scope of the application. Knowing the priority of each
use case lets you design the architecture accordingly.
- Status: Notes how complete (or incomplete) the development of the use case is.
- Preconditions: A list of conditions that must be true before the use case
starts.
- Postconditions: A list of conditions that must be true after the use case
is complete.
- Use case interactions: Identifies other use cases the use case interacts with or
relies upon.
- Flow of events: A list of events that happen during the execution of the
use case. This could also contain alternative paths.
- Activity diagram: An activity diagram or diagrams of the flow of events
or some part of the flow of events.
- Secondary scenarios: If the flow of events contains only a primary
scenario, then here secondary scenarios might also be documented.
- User interface: A simplified picture of the user interface for the use case. A prototype of the user interface helps the development team see if the design is on the right track.
- Sequence diagrams: Sequence diagrams of the different scenarios.
- View of participating classes: A diagram of all the classes whose
instances work together to implement the use case.
- Other requirements: Other requirements might include quality attributes if you
do not have a specific document for them.
To help you see how the diagrams and documentation come together, I'll show you how I would document and then diagram the Login use case for the example application. For the sake of simplicity I've left out the user interface prototype and the other requirements (that is, quality attributes) below. I'll explain how to document quality attributes in the next article of this series.
Below is an example documentation for the Login use case.
- Name: Login.
- Description: This use case handles the access to the system. If the user
has no access (that is, is unregistered), he or she will be directed to a registration page.
- Actors: Customer, Customer Representative.
- Priority: Very important.
- Status: Started.
- Preconditions: The user has browsed to the Web store's front page and
filled in his or her account details and must now log in.
- Postconditions: (1) If the user was in the system, he is logged in and has
access to the system; (2) the main menu is shown to the user; (3) if the
user was not in the system an error message is shown with a
possibility to register for the site.
- Use case interactions: None.
- Flow of events: basic path: (1) The use case starts when the user browses into
the Web store's front page; (2) the system will display the front page
with text boxes for username and password, a button for accepting the
information, and a link for registration; (3) the user enters a username
and password; (4) the system checks the information; (5) the system
displays the front page with user-specific information; (6) the use case
ends.
- Alternative path: (1) The use case starts when the user browses into the Web store's front page; (2) the system will display the front page with text boxes for username and password, a button for accepting the information, and a link for registration; (3) the user clicks the link to register; (4) the system displays a registration form with text boxes for name, address, telephone number, and e-mail; (5) the user fills in the information and accepts it; (6) the system loads a page where it shows the information again and asks the user to verify it; (7) the user verifies it; (8) the system gives the user guidance to accept the registration by checking his or her e-mail; (9) the user checks his or her e-mail and clicks the confirmation link; (10) the use case ends.
Diagramming the login use case
Following are the three diagrams called for in the documentation template. The activity diagram depicts the flow of events or some part of the flow of events.
Figure 5. An activity diagram
The view of participating classes depicts all the classes whose instances work together to implement the use case.
Figure 6. View of participating classes
A sequence diagram depicts the different application scenarios (use cases) as a sequence of actions.
Figure 7. Sequence diagram
In this third article in the series on designing software architectures, I've provided an overview of the elements that make up an ideal requirements specification. While you might never write a requirements specification, you will read many of them in the course of your work as a software architect and you might also, from time to time, find yourself in the position of guiding other members of your team (such as the requirements analysts) toward writing better ones. The guidelines in this article should help you in that process.
Of all the elements of the requirements specification, the use case documentation and diagrams can be the most important to the software architect, providing both concise information about the application and a visual framework (or blueprint) to work from. Use case documentation usually focuses on the functional requirements of the application. In the next article in this series I'll introduce you to the various ways you might find quality requirements documented, as well as discussing what they are and why they're essential to your work as an architect. So tune in then!
In the meantime, please do let me know what you think of this column and this series so far, and feel free to suggest topics you would like to see covered in the future.
- See Mikko's "
Designing software architectures, Part 1" (developerWorks,
October 2004) for an overview of the architectural design process.
- "
Designing software architectures, Part 2" (developerWorks,
November 2004) continues the series with a look at the role of the architect.
- Granville Miller's UML modeling
workbook (developerWorks, May 2001 through June 2002) is a hands-on introduction to use case development and the Unified Modeling Language.
- "Documenting
software architectures" (The Rational Edge, January 2004) is one
architect's account of the importance of good documentation in large-scale development
projects -- as well as a review of a book worth reading.
- "
Reference Architecture: The Best of Best Practices" (The Rational
Edge, January 2004) is an excellent discussion of the benefits of
RUP in software design and development.
- "Risk
reduction with the RUP phase plan" (The Rational Edge,
September 2003) is a more example-driven look at how RUP works in a
real-world software development project.
- Don't miss a single installment of Mikko's Architectural
manifesto column! See the column series page for a
complete listing of previous installments in this series.
Mikko Kontio works as a Technology Manager for the leading-edge Finnish software company, Softera. He holds a Masters degree in Computer Science and is the author and co-author of several books, the latest being Professional Mobile Java with J2ME, published by IT Press. Mikko can be reached at mikko.kontio@softera.fi.
