Are You Making Use Cases Too Difficult?

by Gary K. Evans

While properly constructed use cases are very easy to write, I still see project groups - that are otherwise very capable - making this a much more difficult exercise than it should be. Here is a brief guide to writing a use case in the simplest possible way.

A Simple Process for Writing the Use Case

1. Identify the name(s) of candidate use case(s) in your system

You can do a use case diagram if you wish, or you can just put the use case names in Excel or Word. Your goal should be just to gather names that you think identify potential use cases. Don't worry yet if the candidate is a real use case.

Then, for each candidate use case:

2. Write a brief description of the function or feature the use case represents.

This is often called the abstract, or summary, of the use case. A one or two sentence summary allows a reader to understand quickly what benefit this use case provides, without having to read the whole use case and interpret the content.

3. Write the goal of the use case.

The goal is what will be achieved when the use case completes successfully, that is: the business value delivered by the use case. If you cannot articulate the goal, then your candidate might not be a use case.

4. Write the happy path for the use case.

The happy path is that set of steps that achieve the goal of the use case. By first limiting yourself just to the happy path, you will not be distracted by all the many things that can go wrong, and by focusing on the happy path you will quickly learn if what you identified as a use case really is a use case. As you write the happy path:

1. Capture names (only) of alternates/extensions as they occur to you. Write these names at the end of the use case so you don't forget about them.
2. Get the happy path validated by your end-user/user community.
   Someone has to have responsibility to critique your use case. Assure them you will fill-in the alternates & extensions later. Rework the happy path until they approve it.

5. Write the behavior of the system for each alternate/extension.

After your happy path has been approved, then start writing the behavior in each alternate path, specifying what the system does to recover and return to the happy path, or if the system aborts the use case.

6. Get the entire use case validated by your end-user/user community.

This step allows your reviewer to see all of the specified behavior for the use case in a unified, single offering.

Five Tips for Useful Content

1. Focus on the interaction between user and system, not the system's internal behavior.

The great motivation for doing use cases is they should focus on the needs of the user. Save the specification of internal behavior for system design.

2. Write each step of your use case in active voice, present tense.

Grammar may not be your strong suit, but when you write a use case you are a writer, not an analyst, or developer, or tester. For some guidance on voice and tense see this article.

3. Indicate clearly who is "kicking the ball"...the user, or the system.

Sentences such as "Get account number" or "Request matching items" have no subject. Who is doing the "getting"? Who is making the "request"? Be clear, be simple, and be a good writer. And don't forget to identify your secondary actors and where in the use case their services are invoked.

4. Group multiple steps if you wish, or keep each step discrete with its own step number.

This is simply a style issue, not a matter of grave import. Allow some flexibility in expression so people can exercise a little creativity.

5. Be economical in your writing.

Write for your reader, not yourself, and write only enough to convey what the system will do to meet the users' goals. If your reader wants more information, you can add it if they ask for it.

    Gary K. Evans

Template Tyranny

Templates for project documents are a valuable source of standardization. Consultant Scott Ambler has noted that they are also one of the most fruitful forms of reuse. But templates have several downsides that can very adversely affect a project.

The foremost drawback is to use the template's structure to guide the discovery of the template's content. Simply put, templates are not for discovery. They are for presenting what you have already discovered. Their explicit, and highly organized, structure too often imposes itself on the people trying to discover project information. But discovery is neither plannable, not organized. Discovery can range from chaotic to chaordic (on the cusp of chaos and order) - but discovery is never very pretty or well-mannered. Rather than let the template dictate what you should discover next, let the template simply be the repository for your discoveries.

Templates dramatically affect a reader's expectations. Templates neatly organize information into the standardized content categories of the template. But when your content is tentative, and still half-baked, putting it into a neatly structured template leads your reader to assume that content is finished, accurate and trustworthy. Marking a section as "TBD" or "TBC" is very desirable to properly manage your reader's expectations - and your own: if you don't explicitly comment content as unfinished and not-fully trustworthy, you might yourself forget to revise that content 3-4 weeks later. You could end up believing your own unfinished content. I have also found I can very favorably manage reader's expectations regarding drawings and UML diagrams if I place into the template digital photographs of diagrams done on whiteboards. These look messy, and unfinished, and no one has ever mistaken them as finished. Keeping your reader's expectations in check can save many misunderstandings later.

In our Western culture we expect to read documentation from top-to-bottom, left-to-right. When we are confronted with a template with many sections or paragraphs to fill-in, we often approach adding content with the same expectation: going from the top of the template to the bottom, we fill-in each section in this sequence. But the order of presentation in a template may not be the order in which we discover that content. My favorite example of this is a use case template: preconditions first, happy path next, then exceptions and alternates. But the preconditions cannot really be known until you have written all of the happy path, and you might identify some of the extension behavior even before you know all of the happy path. Don't add content just to have something in a field or paragraph.

Templates are expected to be fully filled out when read. But the content of a template is constrained by an implicit time dimension. Some information in a template can be identified early in a project; other information is not accurately known until later in a project. A person filling in a template may not be willing early in the project to leave these later fields unspecified. The flaw that can occur is that the writer may put information into such a field anyway because he or she is unwilling to simply leave the field blank. Once content is placed into a field, only a careful reading will reveal that it is inaccurate, or worse, misleading. Don't add content if its time has not come.