— A reprint of an article written by Sharon C. Evans from the Canadian Information Processing Society Magazine

Recently I’ve been asked yet again about best practices in writing use cases. I started researching this very topic back in the mid 90’s when there were really only two authors on the subject – Alistair Cockburn and DeChampeaux. They have become the ultimate in theorists, and really don’t make up such lists.

The three amigos have revolutionized use case analysis by releasing the Rational Unified Process, and Information Technologists have embraced their methods for documenting business requirements. Reading the Rational Unified Process in detail is actually your best clue on the subject.

Best Practices…

In discussing the topic of best practices, it is safe to say that there is no right answer to every question. There is a lot of “it depends” when a question is posed “what is the right way to document this in a use case”. There are a few methods, depending primarily on context, and the business environment in which the requirement specifications must be used. Some environments are lacking the role of application designers, so more design details need to be included. Other environments have many distinct roles, and this becomes a pure business documentation exercise.

It is most likely safer to discuss what should never be seen in a use case.

If there were such as thing as the Use Case Police, these would be their primary citations:

The first – cutting and pasting legacy code into a use case document – Oh my goodness – do we really need to explain this? It is done so many times and it just shocks me every time.

Although we may have business rules and logic embedded in this stuff, it’s someone’s job to unravel the mess, and guess what – it’s yours! Pull out the business rules, and put the rest into the documentation. There has to be some steps or functions, and they can be documented, no matter how daunting it may seem. I’m not saying that this stuff should never be seen in a document on an OO development project, just not in a use case. Leave this stuff to “supporting documents” or inputs to the use case.

The Second Problem…

The second problem – Including If/Then/Else Logic. Let’s face it – Actors make choices, and they aren’t always sequential. When the actor gets to a cross road, list the options they may take and then return to the “happy path” or the instance you’ve chosen to author in this use case. You can always put links or references to other use cases, extensions, business rules or requirement statements to document your “branches”.

It’s Not Decomposition…

The third situation – making use case writing into an endless decomposition project. A common approach taken when software practitioners first try their hand at use case documentation is to determine the main functional capabilities of a system. No problem yet. The high level use cases are then distributed to an individual or team and they decompose or elaborate it into several more detailed use cases.

There is nothing wrong with this as long as the main goals of the system are kept in mind, and that common functions or actions are extracted and then shared and integrated. Keep in mind that objects are not functions, and functions are not objects. Duplication of effort occurs when one of the primary functions is not seeking out the common components. It is also necessary to document the interactions between the components, which often gets missed when using a decomposition method. System integration is only possibly when the whole vision of functionality is kept in mind.

Remember the Actor???

In no particular order, the fourth situation I’ve seen is forgetting about the actor – Remember the Actor? Yes, the poor little stick dude that this whole world is supposed to revolve around. I’ve seen use cases that forget what this poor little guy wants to achieve. When choosing the “happy path”, or scenario that this use case describes, think about one particular Role (definitely not a position within your firm), and document one instance of a function this actor wishes to provide within your business world.

Never forget why he came here in the first place. Give him a place to start (the good old “this use case begins when”), and definitely do not let him leave the building unannounced (with the ever wonderful “this use case ends when”).

Don’t forget how he got here in the first place by setting context within pre-conditions, and if he supposed to do something when he leaves, why don’t you document that in the post-conditions section? Does the Actor have way too many friends, and not enough attention is paid to the Guest of Honor? You guessed it, pay attention to the Primary Actor in the use case and you will have avoided this mistake.

Now the actor is more important than ever, as the actor becomes especially important when it comes to developing complex systems such as Web services, where external interactions play an important role in the system design. Remember that the actor can also be an external system, and the interactions between systems and services are best depicted pictorially or with models such as activity or sequence diagrams.

Recall the King of the sequence diagram? Who sits atop, reigning over his very own swim lane? – Yes – you guessed it, it’s the actor again. It is important, when we initially conceptualize a system, to identify the actors that will impact that system. Understanding the interplay of requirements and services between our system and its actors lets us allocate system resources accordingly. The actor’s role in a system determines the degree to which it may impact the system.

Don’t Drop Anything!

The fifth problem – dropping the ball – Remember the “hot potato game?” You’re supposed to pass something around pretending it’s hot and do not drop it between yourself and your neighbour. How about “the dangling participle” from your school days grammar teacher? Both of these have something in common with use cases. There can be lots of opportunities to miss a step, or not link them adequately. Each step must flow through to the next, and the reader/developer or designer must clearly understand what is to be achieved.

It’s Not About the Interface – It’s about the Business Problem!

The sixth problem – including too many user interface details. Sometimes, a writer chooses to document a use case in terms of the use interface. Push this button; navigate to here, do that. Instead, pick one actor path and use generic terms to advance through it. Use terms that will work one day when “buttons” are gone and maybe even browsers! Use terms that are common to the business such as “select this” and “save that”. It’s always going to be about choices and ramifications, so document that.

The seventh and final problem listed here – writing the use case without setting context. I’ve mentioned this one earlier, but not in enough detail. A use case is only as valid as the content in which it is written. Think about a play – there is scenery, and sometimes even a narrative about what the actors are about to do. These can be documented in your preconditions and post-conditions. If needed, put some context into your basic description that leads into the entire use case. Use the assumptions section to describe any of those you might need.