Really Strategies

• Articles
• Presentations
• White Papers
• Newsletters

State Your Case

by Joseph Barnes

Sometimes, it makes sense for a publisher to build a custom software solution rather than to acquire one. And whether it's a content management system, a content delivery system, a workflow management tool, or some other type of system, you need to define effective requirements to ensure that the design and ultimately the software that's built accurately reflects your project's goals. In previous articles we've talked about structured methodologies for designing software. In particular we've mentioned use cases, which are our preferred means of documenting business requirements. In this article we'll dig a little deeper by providing some specific examples of User Cases and their counterpart, Sequence Diagrams.

Use cases are a means of describing requirements from the standpoint of a specific application use scenario—how one type of user will interact with the system to perform a particular task. This provides an easily readable view of the business requirements for non-technical staff reviewing them, as well as a specific set of goals that can be translated (or realized) into more technical documentation for the software developers involved in the project.

At Really Strategies we've created a development case (i.e., a framework for business and technical specifications) that incorporates use cases as the primary means for capturing business requirements. Our use case report template consists of a series of metadata elements about the scenario as well as natural language descriptions of the expected action flow and desired results. This breaks the use case report into two distinguishable sections.

The following example shows the metadata section for a standard "Login" use case.

Login Use Case Report

The next section of the report, the natural language description, deals primarily with the definition of success for the use case. This section talks about the flow of the scenario including alternate possibilities as well as any other issues or remarks that should be stated about the use case.

The following examples illustrate the natural language descriptions for the "Login" use case.

Main Success Scenario

Alternate Scenario(s)

Issues/Remarks

As you can see, the requirements are reflected primarily in natural language form making it easy to take the next step—realizing the design of the system.

It's possible to range from extremely simple to highly detailed in your approach to use cases. The level of documentation greatly depends on the task at hand. The template we've illustrated in this article is a modified version of the Unified Process use case template that we've found works well for most publishing system development and publishers.

The F.A. Davis Example

Recently we employed this development case in the construction of an improved editorial workflow system created for F.A. Davis Company, a publisher of medical reference materials. Our focus for the project was to replace the functionality of the existing component (document or object) workflow system and to provide enhancements that account for multiple output types and the storage of multiple document and file types. Based on these high-level requirements, the following is a subset of the use case reports that we defined for this project:

• Add Components
• Check-in Components
• Select Repository
• Browse/ Search Components
• View Component Properties
• Check-out Components
• Export Components
• Select Product
• Maintain Product Properties

These report titles are broad enough to avoid being unnecessarily bogged down by the level of requirements detail needed during the system design. This is a very important aspect of creating a development case that works for your organization. Requirements must be gathered in enough detail to accurately describe the potential actions taken by the user, but not to the point of obstructing project productivity in the process.

As alluded to in the previous section, once the use case reports have been defined the next logical step is to highlight the architecturally representative ones in the form of Sequence Diagrams. Sequence Diagrams represent the move from natural language-based requirements to a structured system design format. The sequence diagram helps to show the development team what types of calls are imagined from one architectural layer to the next. Typical system users are not expected to see Sequence Diagrams. Instead, they are used to ensure that developers fully understand the complexity of the software they need to build before they begin writing code.

The following example illustrates the Sequence Diagram for the "Select Repository" scenario in the F.A. Davis system design.

It's important to note that the size of this project was relatively small. We were to perform the analysis, design, development, and deployment of the system in less than 6 months time. By defining a clear set of use cases as the baseline for requirements and adhering to the project schedule, we were able to meet our goals within the timeframe allotted. This type of success comes primarily as a result of the prior structure of our development case for this type of project. We knew going in exactly what level of detail we required to design and build a system that would meet our client's needs. Highlighting this point, the project team at F.A. Davis was extremely receptive to the approach. The use case reports were used as a baseline for the test plan and functional reviews of the software during the development phase of the project as well.

In summary, the development case for this type of project consists mainly of use case reports, sequence diagrams, and a handful of supplementary specifications for capturing requirements that don't easily fall into a use case bucket (such as performance requirements). Take your time to learn what development case works best for your organization. But whatever you do, keep in mind that the key to success is ensuring your requirements define what success is.