Making of a Web App: Part 9 – Why I Hope No One Reads My Use Cases

Use Cases

Briefly put: a use case can be anything that documents how a person will accomplish a task with your application and how the application will respond. In this article I use the term to mean written use cases (as opposed to diagrams or sketches).

Click here for an example.

Some developers do not write use cases because doing so feels too much like writing documentation and documentation is not the purpose of building a system. So, in an effort to work only on things that directly contribute to building the app, people skip over the use case step and jump right to visual design or sketches (or even just start hacking out code). I have to say that back in my developer-only days, I was that way too. I saw anything but code as wasted time. Now, I don’t. Here are four reasons why I don’t skip the use case step.

1. Use cases contribute directly to the final, deployed app.

Use cases become user documentation (aka help files).

If done right, use cases are not thrown away work that gets shelved after the project is complete. There is at least one part of the final delivered app to which use cases contribute directly. There is a part that is often forgotten or saved until the very end and done as time allows. It’s the part of an app that I hope no one ever uses. It’s documentation and help files.

Typically, a development effort completes and then everyone scrambles around trying to figure out how the documentation is going to get written. Just like writing test cases first, writing the use cases first is good practice.

Unlike test cases though, use cases in the form of help files are, honestly, something that I hope people don’t read. If people are referring to the help files, that means the design is not clear. If people stop their work and have to look up what to do next in a help file; then the design does not communicate the intention of each screen and button clearly enough.

So here we are; even though I hope people do not read it, people still expect documentation and documentation ups the level of professionalism in an application. How to solve this dilemma? By writing use cases from the perspective of people using the app. This way I can use them as both a design tool and part of the delivered app.

Here’s an example. Instead of writing:

1. User selects the playbook dropdown.
2. User selects a playbook.
3. User clicks ‘Save’.
4. Milestones are copied from the playbook template to the opportunity.
5. Tasks are copied from the playbook template to the opportunity.
6. A history record is created with date, time, and username of the current User.

I wrote:

When you select a playbook in the Playbook field and save the opportunity, a few things happen:

1. Milestones and tasks are copied from the playbook into the opportunity.
2. A history record is created recording the date, time, and current username.
3. Any milestones and tasks assigned from previous playbooks are not affected and remain unchanged.

For fans of agile development or Getting Real methods, this seems dangerously close to written documentation. Yet, as I said before, people will expect some form of documentation anyway and using this method ensures we are not running around after the fact trying to figure out how documentation is going to get written.

2. Use cases expose risks to simplicity

In moving from conceptual to concrete, the devils in the details come out.

PlaybookIQ is a great example of the ability of use cases to expose complexity from its favorite hiding spots. At the conceptual and task-flow level, the relationship between contacts, opportunities and playbooks seems quite simple.

• A contact is a person.
• An opportunity is a chance to provide products or services to one or more contacts.
• And a playbook is a series of best-practices to follow when pursuing an opportunity.

Simple.

Except it’s not. It was not until trying to write down the relationships between contacts, opportunities, and playbooks that the complexity was revealed. I won’t go through the details here because this series is not about the app, but rather the process and experience. The short version is that writing use-cases exposed a decision that needed to be made. I found I need to decide: is a playbook applied only to opportunities, only to contacts, or to opportunities and contacts. (If you have thoughts on this decision – let me know because I am still working it out.) Drawing the three with arrows between them all makes it look simple. Writing use cases describing the interactions shows there are more questions that need answered.

3. Use cases expose the level of development work required

One screen is not like another.

If I find myself dreading another sentence when writing the short use cases, I know I will have an even worse time being motivated to write the code. (And an unmotivated coder is one of the worst risks to a project ever. Studies have shown that motivation has a larger impact to programmer productivity – both positive and negative – than any other factor.) A screen sketch just does not capture the depth of interaction and decision-making that an application will be asked to perform. By better understanding the scope and level-of-effort a feature will take, I can better plan the project and make smarter decisions on what should be cut.

Why not just write code now then? It is easier and quicker to change words than it is code, and it is easier to communicate to other stakeholders in words than in code. That’s why.

4. At this stage in the project, use cases are the easiest way to iterate, collaborate and communicate.

Everyone can read, understand, and edit a text document.

ConceptShare is a popular online design collaboration tool, and paper and pencil work well for teams working in the same room. The tools are there, yet people are still more familiar with editing text documents than they are with editing others’ drawings. Some people communicate and learn better with visuals, some with words (and some are audible learners – but no one I know is a “scent learner”, go figure). So while there are visual communication tools out there, they are better put to use when the visual crowd gets their chance later on in the project.

Communicate: Use cases communicate much more than just what screens and fields are required and how they will interact. Use cases are also a great place to write down definitions of key terms and overall expectations of the application. For example, this is from the use case for PlaybookIQ opportunities:

An opportunity is a chance to provide products or services to one or more contacts.

Where would someone put that in a screen sketch? Short descriptions like these help ensure the development team and clients are on the same page and, as mentioned earlier, this same document becomes help material. As final bonus, this document can also be marketing material or at least information that goes on a product site.

Back to Reality

Now, back to reality. I cannot write all day without visual representation is being written about. So, in reality, I sketched up some rough task-flow diagrams and then iterate between use cases and task-flow diagrams.

I draw with pencil on 5” x 8” index cards, then spread those out on the desk, floor, or white-board to visualize the relationship between each major component. Each iteration aims to simplify and clarify how tasks will be accomplished. Because it’s not in soft copy, I need to take some pictures to show what that looks like and will discuss them in a later post.

Enough of this evil documentation work already.

I hope you can see that written use cases are not part of the evil tree-killing conspiracy, but are a useful communication tool that also becomes part of the finished product. And to clarify, like all entries in this series, I cannot tell you how to build your web-app. I don’t know your technical, environmental, or political situation. I’m just sharing what I do. That’s why it’s called “Making of a Web App” and not “How To Make a Web App”. Either way, I know most of us will be glad to move onto something a little more visual and closer to what people think of as the application: screen sketches.