 | Level: Introductory Mikko Kontio (mikko.kontio@softera.fi), Technology Manager, Softera
13 Dec 2004 Even if you never write a requirements specification, it's important, as a software architect, to know what separates the good ones from the bad. Learn the fundamentals of writing a good spec and then pass on what you've learned to other members of your development team.
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.
Documenting the application
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.
Use case diagrams
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
Use case modeling
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.
Documenting the use case
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.
 |
An example use case
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 conclusion
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.
Resources
About the author | | |
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. |
Rate this page
| |
