Thoughts about Writing Use Cases and User Stories

Every now and then people ask me about how to write use cases, preferrably ones that are usefull. I admit this is giving me fixed feelings: I'm happy to help and I'm pleased that people still find value in these, but at the same time I find myself feeling annoyed and disappointed about how rarely projects utilise Use Cases these days.

Before agile processes became the hype they are today Use Cases were the bread and butter of any new development project that (when done properly) allowed architects to think things through few times while writing them, explained to the developers what was needed and how things should happen as well as gave the testers a solid base to begin writing their Test Cases. After all, from a good Use Case several Test Cases could be derived starting from the Happy Day -test scenario.

But I digress.

A Use Case describes a single operation performed by the end-user, such as New User Registration, User Login or Search by Using Key Word(s) without addressing techical implementation details in any way. In other words, a Use Cases explain who uses the system in question, what they can do with it under which circumstances.

When writing Use Cases one should usually imagine another user operating the system through specific user interface. There are several questions that need answering: what is the user trying to accomplish? What information the system needs in order to help the user? What individual steps user needs to perform in order to reach the goal? Does the Use Case include interaction between the user and the system? How to keep things simple and intuitive?

Basic Use Case Structure
When I'm writing Use Cases I typically utilise following basic structure. While various books and processes introduce Use Cases with quite a few more fields than what I have listed below, my experience has shown that these are the ones most commonly needed.

UC FIELD	DESCRIPTION
ID	A unique identifier for the given Use Case. [group id] - [use case number] For example, ProjectAwesome-42 or UC-001. A good notation provides identifiers that are unique, clear and informative within the given project context. Note: A common mistake is to refer to a use case by its title, document chapter or even document page number. All these are likely to change during writing and editing which would then propagate to all those other documents that reference the Use Case.
Name / Title	The name of the Use Case. For example, Create User, or Request New Password. Note: A good name typically follows verb-noun format (do someting). Keep it simple, keep it clear.
Summary	Short verbal description explaining what this Use Case is about. Few sentences are usually enough. For example, The user creates a new user account by submitting the registration form containing required and possibly additional optional personal information.
Priority	Describes how important this Use Case is considering the overall usability of the system. During the early stages of the planning a priority hierarchy of three levels is usually enough: (1) Essential: The system will not be production ready before this UC has been implemented. A core Use Case. (3) Normal: This UC is needed and once implemented will greatly improve the overall usability of the system, but it can wait until the essential Use Cases have been implemented first (it is likely that this UC cannot be implemented before some essential UC). (5) Nice-to-Have: While this UC could be beneficial for the end-users and improve the overall system, it is not strictly speaking required. Can be implemented should there be time and resources. At later stages the priority hierarchy can be expanded to include five levels especially if there are large number of Use Cases with the same priority (and there often is). It also helps to highlight which Use Cases enable the development of other Use Cases.
Actor(s)	Actor is an end-user archetype, or a role that can utilise this specific Use Case. For example, Anonymous, Customer, Admistrator, Secretary Or Client Service. Each Use Case can have one, two or several actors. It is also good to keep in mind that end-user roles can evolve over time: one and the same user could begin as an Anonymous user when she enters the Create User UC; after successful registration the end-user might become a common Secretary user until she is given the Administrator privileges after which she might retain both Secretary and Administrator roles. Note: It would be a topic for another discussion to consider whether Administrator should automatically include Secretary privileges or should they be kept separate at all times. After all, is the Administrator suppose to also do what Secretary does or should the concerns be kept separate at role levels? My opinion usually is to separate the concerns and enable the assignment of multiple roles when needed.
Preconditions	What must have happened before this Use Case can be accessed? For example, User has logged in or Account has money. Often a Use Case can be a precondition for another Use Case, such as the requirement that the user has logged in. When this is the case use Use Case ID and Name as precondition reference (e.g. UC-003 Login User). Another common situation is where certain property value(s) act as precondition. For example, UC Withdraw Money cannot happen if the user's account has no money.
Steps	What the Use Case is actually about is explained here step by step. For example, Start: Actor enters Login screen. Step 1: Actor provides username and password to appropriate form fields. Final Step: Actor clicks Login button.
Post-conditions	Post-conditions list key changes in the system after the Use Case has been completed. For example, after successful login the post-condition could be User has logged in and can access privileged services. Or if money has been withdrawn from a user account the post-condition could be the updated account balance and closed transaction.
Exceptions	Where as Steps essentially explain the Happy Day -scenario (e.g. when everything goes as typically expected) there are usually various foreseen exceptions. Most common example is a failed field validation. For example, Login might have following exceptions: E-1: Incorrect username: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password". E-2: Incorrect password: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password". E-3: Account locked: The Actor is taken back to the login screen and an error message is shown: "Unable to login: user account has been locked. Please contact customer service for support."
Comments	As Use Cases tend to go through multiple revisions it is often useful to have a place for comments and suggestions.

A bare-bones Use Case might do without pre- and post-conditions and priority, but eventually somebody has to figure these out before the Use Case can be implemented.

Use Case Iterations
Use Cases typically evolve through multiple iterations. Consider following:

First version: Once a need for a UC has been identified create the basic structure with just ID and Name.

Second version: Think about who needs this use case and what actually should happen on a high level. This defines Actor(s) and Summary.

Third version: Dive into details and think step-by-step what information the system needs and through which actions the end-user should provide that information. Each step might have 0..n (zero to many) exceptions so which ones can you identify at this point? More can be added in following iterations.

Fourth version: After most of the system's use cases has been identified are there some obvious Use Cases or property values that would act as preconditions to other Use Cases? Often one comes up with a precondition only to realise that it is actually a new Use Case.

Fifth version: Through discussions with various stakeholders and reviews Use Case begins to shape into its final form, but there are likely to be some more changes along the road...

Use Cases vs. User Stories
Use Cases are similar to User Stories often used in Agile processes such as Scrum. The main difference is that User Stories tend to be high level prose where as Use Cases are more structured and detailed.

Consider following example describing a user login.

USER STORY: Anonymous User Logs In
Description: The user opens the login page where he must provide valid USERNAME and PASSWORD combination. The basic form validation checks that the USERNAME exists, PASSWORD matches the one in the database and that the account is active. After successfull login user can access all functionalities according to his role privileges.

How to demo: First try to access some functionality that requires user to login. This should fail and user is automatically taken to login page. 

Next try login with incorrect username and/or password. The login page reloads and shows appropriate error message.

Finally login with valid credentials and after successful login attempt to access the same functionality as before login. This time functionality can be accessed.

USE CASE: Anonymous User Logs In

ID	UC-02
Name / Title	User Login
Summary	User provides required login credentials in order to gain system access.
Priority	Essential
Actor(s)	Anonymous
Preconditions	n/a
Steps	Start: Actor enters Login screen. Step 1: Actor provides username and password to appropriate form fields. Final Step: Actor clicks Login button.
Post-conditions	User has logged in and can access privileged services.
Exceptions	E-1: Incorrect username: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password". E-2: Incorrect password: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password". E-3: Account locked: The Actor is taken back to the login screen and an error message is shown: "Unable to login: user account has been locked. Please contact customer service for support."
Comments	n/a

Thoughts about Architect+Product Owner

When it comes to scrum and agile way of working I consider myself a pragmatist, not a purist. As far as I'm concerned, process' value is determined by how it can be adapted to project's special characteristics while still doing what it is supposed to do: provide a sensible and practical framework for productive work with minimum managerial overhead.

Now, I admit I'm the last one to assume any position of authority: I have no certificates, nor have taken any courses or spent hours arguing about the theory. Well, scratch that last one - I have argued about the theory, a lot :) Mostly with people who got their certificates after taking courses and attending seminars. The only thing I can base my opinions is my meandering practical experience.

Not too long ago I worked as an architect in a major customer platform project, but due various practical reasons I had to function also as the ScrumMaster and Product Owner as well. Sounds bad, I know, but at that time it was the only way to get things working and indeed, we did quite alright and everybody were happy. I kept wearing three hats for about four months and during that time I made an interesting observation: I was better able to communicate and control the implementation of my architectural vision and design through product owner's methods and channels, while also receiving more useful information directly from the stakeholders. In other words, the quality of user stories and information available to the scrum team improved (says I) and the overall vision of what we were working on become clearer.

It makes sense when you think about it. A good architect has most if not all capabilities and skills as a good product owner has, but in addition architect is better suited to design and explain to techies what needs to be done. A good architect is fully capable of negotiating with various stakeholders and to understand business needs and requirements, all of which is information architect would need anyway to do his work. A good architect can write the scrum user stories from the business end-user's point-of-view and explain it all to scrum team's developers and testers. While a sprint is on-going the architect-PO can keep the backlog in healthy shape, keep in touch with stakeholders, provide support to the team members and work on design documentation as well. And when the team shows how they implemented the user stories, who else would be better suited than an architect-PO to evaluate whether or not the implementation is acceptable?

Now, I can almost hear purists gasping air in aghast... calm down and breath deep. Can you really give any valid reason why this shouldn't work apart from "this is not how things are supposed to be done in Scrum"?

And are things any better now that there is a another person doing the Product Owner's work? In my opinion, no. He has no prior experience from scrum projects, he has not received any scrum training apart from two hour tutorial that was arranged by our company nor does he bother about writing user stories (this is typically delegated to the team ScrumMaster, instead of project architect), which in any case often tend to contradict prior design, implementation and/or plans. Neither does he use ScrumWorks (or any other available tool) efficiently, he cares more about new features than quality of existing features and removal of technical debt (and he used to be a test consultant!) and bullies the team to accept more user stories to sprints than they should. Caveat: But I'm being unfair here, the man does his best under never ending pressure from the business and within the confines of his organisation's politics and business practices. I even have to admit that often I had to agree with his reasoning even when I disagreed with his methods and solutions. All and all he is a good man and I respect him.

The reason why I brought this up is to point out that while the theory might sound good when a lecturer explains how much better things will be once Scrum has been properly adopted, the reality check can be quick and harsh when the theory is being implemented in practice. Admittedly, often it tends to be a acute case of "people are the problem", as Douglas Adams to apptly put it. 

It is not practical nor even possible to expect all involved people to adapt to the process, and this is only emphasised when a subcontracting organisation tries to introduce Scrum to a customer organisation (why should they even try, you ask? Often a customer organisation might have no knowledge about IT processes and you do need one, whatever it might be). The process should be able to adapt to people, organisations and project specific aspects. And when the process reaches its limits of adaptation? Well, try another one - perhaps one that is approximately closest to overall starting point?

The Architect's Point-of-View

What about the architect's point of view, then? Gone are the good old times when architects were allowed, even expected to reside in their cozy ivory towers; absent mindedly looking down where plebs... er, developers were slaving away long hours to implement the architect's latest vision of grandeur and excellence. Time has become a rare commodity in projects and no longer are architects given ample time to think, to plan, to ponder, to design and to document before development is even started. Somehow ivory towers got demolished when architects weren't looking and now many of them are standing amidst the tower ruins wondering what they should be doing next.

Obviously a good architect is ready and willing to jump into the trenches and get his hands dirty. Except... a scrum team does not recognise roles, like the one of architect. Everybody are developers, everybody are architects, everybody are testers. No specialities, just a regular cornucopia of Jack-of-All-Trades (well, lets be fair: things are not as bad anymore, now it is alright to have technical testers in Scrum teams). So, should an architect become a developer and participate in writing code along with other developers? Not necessarily a bad idea, but while doing very detail oriented implementation work there is not much time to think about the big picture, about how all those nitty-gritty details end up forming something that actually works. This is not a problem when the team is working on some reasonably small sclae system, but when it comes to large scale enterprise systems that have multiple sub-systems, third-party integrations, legacy systems along with newly implemented systems, multiple databases and several teams working in parallel... You really need to have somebody who really understands what is going on and why certain sub-systems need to be implemented in certain way because another sub-system that a developer might not even know about, requires it.

And so the architect's role is changing; agile architect rarely gets involved with low-level technical design, which is now done by team developers as they implement sprint user stories, but instead they are likely to start from high-level business requirements specification, designing the overall architecture, defining sub-systems and their interfaces, databases and data structures, support various team members, generally influencing the best practices, do risk analysis, hold customer's hand and of course, produces barely good enough documentation just in time. There is much more to do, of course, all of which places greater requirements on architect's skills. It is no longer enough to just know some UML and key implementation technologies, but one has to have wider range of experience and knowledge that makes it possible to operate various domains (e.g. business, technical, human relations and even politics).

All this makes the agile architect's work so much more interesting if also challenging. Methodologies such as IEEE 1471 helps, but a simple yet practical move to combine the roles of an architect and a product owner can make a real difference, in my opinion.

Thoughts about Agile Development

Not too many years ago RUP was the way to do things and now being agile is the latest "right way" to do things.

It all started with the The Agile Manifesto, which I think bears repeating:

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan.

That is, while there is value in items on the right,
we value items on the left more.

As principles go, this is a good one. In my experience it reflects how things are done in real working life - or at least how they should be done.

The important thing is not to ignore the last sentence: "while there is value in items on the right, we value items on the left more". In other words, the manifesto does not instruct to ignore practical processes, good enough documentation, proper contracts nor having a plan.

I used to work in a company that had taken the agile way and scrum in particular in to the heart. When I joined the company it was actually inspiring to see how not just the techies but the management and even the main customer made a real effort to learn and adapt to the scrum way of working. They were not just talking about it but also working on it. I do respect that.

Unfortunately it wasn't all good. Very few seemed to care about project documentation, because documenting things wasn't perceived as agile. Not true. What people might have been thinking was the old style waterfall process where everything was designed and documented up front any implementation work, but the alternative to that is not have documentation at all. Personally, I think it was just a convenient excuse for people being lazy and cut corners.

Neither was it very common to plan ahead since being agile was to do what was needed right then and there - in my mind to think this way is to be short-sighted. Unless the program in question is the ever-so-popular Hello World, rarely is an application complited in just a few iterations. Incremental iterations are step building towards hindmost goal so one must always be mindful about next couple of steps or the risk of major redesign and refactoring is likely to become an unfortunate fact. Now, surely that is not what agile way of working is supposed to be about?

When Product Owners and managers agreed on the priorities and geared up to get things done, it often became as a nasty surprise when Somebody Else managed to convince directors that their project was more important and should become a priority instead. This wasn't about "responding to change over following a plan", it was more about being without a direction. At one point a project might be a company top priority and then, without warning, be pushed aside and be replaced by another top priority project. I'm sure there were always seemingly good reasons for this, but how is it a good thing when projects go unfinished, professional employees get frustrated and nobody can rely on what was agreed?

Being agile should not be the same as being sloppy and erratic. It is a principle that promotes common sense over dogmatic thinking. About cutting the red tape, doing what needs to be done and getting it done in a professional manner.