Session: “Tales Come True: Use Cases As Functional Specifications”
Presenter: Merryl Gross GE Healthcare

Summary: Functional Specifications may be the most important artifacts in software development (blueprints for what the team is creating), yet they are often hard to maintain and use. Instead, Use Cases, created as a set of wiki pages, can be expanded with UI design descriptions to completely take the place of specifications for a web application. The development team finds use cases much easier to create and maintain, easier to use for test and documentation, and equal to functional specs as a blueprint for creating software.

[MC: E-mail me for the proceedings PDF that contains 107 pages of samples and screenshots!]

Problem with Functional Specs

Writing a functional spec is tough; most are hard to follow, and all who’ve had maintain one knows what a chore it can be when the design changes. Design changes come from many sources: functionality that has been scheduled; customizations that they judge should be promoted; bug fixes; and features being coded “on the side”. At first, she used a Word document to specify what changed in each release. This had many problems:

• Only changes were described. If you didn’t know the base functionality, it was hard to know what you were looking at.
• She had to break the document into sections with repeating format, to document the requirements and design guidelines for each feature separately. This made the document long and repetitive.
• With changes coming from so many sources, she couldn’t keep up with it all; eventually she stopped designing and spent all her time chasing what was being implemented.
• She was the document’s author so she had to update everything, even when she didn’t design the feature and didn’t understand what needed to be recorded. They didn’t have a good way to link related items together, or deal with multiple designers or authors.
• People had to keep up with versions. She was updating the document and putting copies in two places, but folks would print it and never take an update.
• There was no way to notify folks only about things they cared about.
• Most important! When they decided to go agile with incremental releases, the whole plan fell apart. Not only did the document need to contain the design, it needed to be updated whenever a feature moved from increment to increment.

Some use mockups (functional or not) to communicate the design to all parties, but it is impossible to include many types of information in a mockup, which must resemble the UI. Use cases do a great job of presenting the story of using a product. Customers and non-techies can read them and get a feel for how a product will behave. However, use cases that do not describe the UI don’t have enough information for coders, testers, and doc writers to do their job.

Solution: Expanded Use Cases in a Wiki

They decided to try a wiki as a team communication tool, primarily for status and internal docs. A developer installed MoinMoin on an internal webserver and copied a Use Case template from NetObjectives to go with it.  At first, she had no intention that they would give up the Functional Spec; however, as she wrote more use cases, she found that by adding a bit more technical info, she could easily link to the relevant parts of her non-functional mockup or any other information that would communicate the design. Instead of describing the UI page-by-page or issue-by-issue, she describe it in terms of what tasks the user can complete.

They have completed two releases (one with major functionality to describe) using use cases to provide functional specification information. The team evolved organizing principles and standards, summarized below:

Levels of Use Cases

She uses many different types of documents. For complex features, she uses several of them and changes the reference location as the design becomes more complete. She often link steps in the use case to particular pages in a relevant HTML mockup.

0: Usage Narratives (as needed)

These are what Cockburn (“Writing Effective Use Cases”) describes as “informal” use cases. Essentially, they list the actors and tell a short story about a usage scenario. They illustrate an episode of use, so that all the parties can decide whether the design should support it, or get a gut feeling for what life would be like for the actors once the new product exists. They help most in early design stages, where they’re just trying to understand what’s part of the feature and what isn’t. Her example usage narrative was written in under 2 hours and represents a large, complex, and very important episode of use. Target audiences:

• Customer partners who are assisting with the design
• Product managers who are defining the new feature
• Designers of the core applications that provide the data, who want to know what kinds of information might be needed
• Anyone else who wants to know about the feature but no implementation details

1: Kite-Level Use Cases (as needed)

Her kite-level use cases are fully dressed, though written before all the details of the design are known. Best when:

• Spans multiple work sessions for the actors
• Has multiple actors that interact in multiple ways
• Requires an “overview” in order to make sense of the detailed use cases
• Has a usage narrative that isn’t cutting it, and you want something more formal

Hyperlinks within the use case link to the sea-level use cases that contain specification-level information. This enables anyone to get an overview view of the usage, then dive down into the information they’re interested in. Target audiences:

• Customer partners who are assisting with the design
• Product managers who are defining the new feature
• Anyone else, especially developers, who wants an overview of what the feature is about

2: Sea-Level Use Cases

This is the level at which specification information is delivered. Sea level use cases are fully dressed. The Variations section contains important information about how the application should behave in error conditions or alternative paths.

The only variations in the main scenario are for links to the fish-level use cases for each of the possible forms that might come up. Task variations are in the Variation section. Target audiences:

• Developers of the applications
• Writers of test cases and documentation
• Anyone who wants to know exactly what they plan to implement

3: Fish-Level Use Cases (as needed)

Sometimes things get complex. If you try to put a lot of details into a sea-level use case, your readers can lose the thread and get lost. Plus, some readers need to reference the detail and not the scenario. Also, there are some actions (like logging in) that are used in multiple use cases, but aren’t very relevant to any particular one. So when needed, she linked fish-level use cases into sea-level ones.

Example: “Find a patient (so that you can do another task).” The Patient Lookup fish-level use case describes the ugly technical details. When the design changes or grows, she just updates one page, because all other use cases link to this one. This fish-level use case presents field-by-field information, segregated from the main usage scenario but just as available to those who need to know it. It also describes the behavior of the fields when users make specific selections, all according to the customer’s business rules. There are links to other fish-level use cases that describe sub-tasks that might be done while using the page. Target audiences:

• Developers of their applications
• Writers of test cases and documentation
• Anyone who needs extra details about a particular feature

Side Documents:

Not everything fits properly in a use case format. Side pages were linked to from multiple places, so that those who needed the information could find it. Examples: style guide, UI guide

Site Organization

Over the past year, they evolved some organizing principles around their information:

• Front Page: home page of the wiki site. It needs to be convenient and concise for the team that uses it every day, yet understandable to “visitors” who seek to know more about what the team is working on.
• Release Dashboards: created by the project manager, primarily for use by higher levels of management. They teach them to come here whenever they want a status update, rather than bugging people by phone or email.
• Design Dashboards: main index to what use cases are affected by the release. The central table provides links to the mockup, the relevant use case, and provides status information about how complete the design is for each feature. When features were dropped from the release, they are marked as “Deferred”. She also puts notes from the design reviews on this page, so that everyone could easily access this record of their discussions. There’s another page on the site that lists all the use cases available without regard to release.
• Project Dashboards: breaks down coding work by modules or tasks, and displays who they are assigned to and what their status is. The leftmost column is used to link to technical specifications or any other information needed. Before they put links to other dashboards on the Front Page, this is the main spot where they were linked.
• QA Dashboards: links in everything you need to know in order to be a tester, and shows the current status of testing. When they do a “full team push” for test, all the QA manager needs to tell you is what areas to test, and what the URL for this page is. All the information on this page evolved over time, as the plans and test cases were created, and as the increments and schedules were set.
• Workload pages: tracks upcoming vacation time, and what responsibilities the team has other than their current development work. Design Estimates page lists upcoming features that aren’t yet firmly scheduled for a release, and links to design dashboard pages for those that have them.
• Personal pages: (MC: on our site, this would be blogs.)

Conclusions and Recommendations

Using Use Cases as functional specifications has greatly improved their communications. Every team member mines the use cases for the information they need. It has been especially well received by the testers and writers, since it presents product information more in keeping with how their deliverables are organized. Benefits:

• Updates are instantly available to all team members.
• Team members can subscribe to the items they are interested in.
• Use cases can be hyperlinked to each other and directly to the relevant portions of the non-functional mockup.
• Variations in the use case can illustrate different installation and configuration
  options.
• Use cases are retained from release to release and modified when the UIs are redesigned, providing a evolving but complete description of the behavior of the product. No more “delta” specs.
• Team members in all locations can access the same information.
• Everyone can comment and correct the wikis, or add a discussion.
• A use case isn’t needed for every piece of info; just reference it within the task’s use case and create a page that uses whatever format works.
• When combined with a non-functional mockup, developers find it no harder to
  understand what the software needs to do, and easier to ask for clarifications.
• It is easier to write test cases and documentation from the use cases than from the traditional specification documents.
• Individuals can absorb the information in whatever way is best for them. Some like to browse the visual mockup then read the use case. Some like to follow the steps in the use case. They can print the use case or not, as the need arises.

They still have some problems:

• Some developers skip the use case text and go directly to the mockup, missing the details that can’t be presented there. However, that sort of thing is now much easier for testers to catch and write bug reports about.
• Snapshots. They still don’t have a way to bundle of wiki pages to archive them as a snapshot of the release; they visit the history for each page in order to see how things were at any point in time. [MC: I think our Drupal site can solve this.]
• It can be easy to miss the creation of a new document that contains just the info you need.
• If a team member does not subscribe to a wiki page, they don’t get updates. She have taken to writing the team an e-mail whenever she make major revisions.
• There’s no good way to publish the information for folks outside of GE.  [MC: Again, I think our Drupal site can solve this.]