Defining Requirements

You’ve defined the project goals in broad strokes and are talking to someone that can build your web application. The next step is to plan the first stages of the project so that you can start shipping software.

The goal of defining requirements is to specify the desired behaviour of the software you want made in such a way that the developer working on your project can build and ship it. Everything else should fall by the wayside. Consultants selling the benefits of the “Agile” project management technique of the week will try to convince you otherwise. Ignore them and stay focused on shipping software.

Make continuous forward movement on the project. You don’t need to plan the entire project up-front. You need just enough planning so that the developer can stay productive for the coming few weeks. You want to develop a shared understanding of the first few sets of requirements, and then continually plan a week or two ahead of current development.

Tools for requirements definition

One of the reasons that projects fall behind schedule is a mismatch in the understanding of requirements between the client and the developer. You’re using the same words but your mental model of the exact requirements for delivery end up being different. This leads to a lot of back and forth that could have been avoided with more precise planning.

There are a number of tools at your disposal for defining tasks with more precision.

1. Wireframes

One of the first tools to reach for when defining requirements is wireframing. This is where you sketch low-definition outlines of the user interface you envision. You don’t need to build high-definition sketches of what the UI looks like when building the basic functionality.

To create wireframes you can use pen and paper and then take pictures of the screens you sketch with your phone. At Happy Bear Software we use Balsamiq mockups, but there are plenty of other perfectly good wireframing tools available.

2. User roles

Your web application is likely going to have provide for users filling a number of different roles. For our purposes, a ‘role’ is simply a type of user for whom the functionality of the application is different from users of other roles.

Any web application available over the internet has the “anonymous user” role. This is a random user on the internet who hasn’t logged in, usually heavily restricted in the ways they can use your application. Web applications typically also have a “registered user” role that has access to the primary functionality of the application.

Roles can be defined in terms of the level of access a user has. “Admin” users might have access to more functionality or data than regular users. There may be multiple, hierarchical levels of access. The access roles might scoped to an “organisation” or “account” in the system.

Users might also be segmented into roles based on their “plan”. SaaS web applications in particular offer tiered plans. Higher-cost plans usually have more features and higher limits on some form of resource consumption.

You can also segment users by the task they’re trying to achieve. A document editing application might have some users that are in charge of editing and others that need functionality for “signing off” documents for compliance purposes. The application might want to provide slightly different interface to each of these types of users.

Roles might also be defined by engagement metrics like how often the user uses the application, number of records they’ve created, etc. The interface you provide to brand new users that have yet to learn the system might be different from the interface you show to experienced users.

You could also segment users based on their profession, which would be data you collected at registration time. An appointment reminder application might present a different set of functionality to hair salons than it does to psychotherapists for example.

To summarise this list, users can be segmented by:

• Whether they are anonymous or registered.
• Access control and permissions
• SaaS plan tier
• The task they’re trying to complete
• Their level of engagement with your application
• Their profession and desired end-goals with the application
• Any number of other axes along which your users can be split

At this stage of requirements gathering, it’s worth defining your features in terms of the user roles that are important to you. This could be as simple as just “anonymous” and “registered” to start with, but choose whatever is relevant to your project aims.

3. Task definitions

For our purposes, task definitions are a way of describing a single desired change to how your software works. We use a task management tool called Trello to keep track of tasks, but there’s no reason you have to do this. A google document, pen/paper, or whatever allows you to capture the requirements of a task in sufficient detail is fine.

Your task definitions should have three items of information on them:

Name

A very short name for the task. The purpose of this is so that when all upcoming tasks are arrayed in front of you, you’ll be able to quickly recall what this task refers to.

The name is what you write when you’re quickly jotting out a list of tasks that you will discuss in more detail later. There isn’t enough information about the task for a developer to start work on it. All you’ve done so far is capture that the task exists so that you know you need to think about it later.

Description

A description is there to provide a broad overview of what the task entails and why you’re doing it. Some recomend that the description takes the following format:

As a [user role], so that I can [achieve some goal], I want [some functionality that let’s me achieve that goal].

This helps to quickly define which user roles this feature is applicable to, why they need the feature and what in particular they want.

There’s no reason to stick to this formula religiously. If there’s a task for upgrading the Ruby version used by the application to the latest stable release, the description can just be:

Upgrade the application’s Ruby version to the latest stable release.

Once you’ve written a description, there still isn’t enough information to start work on the task. The description serves as a starting point for the conversation you and a developer will need to have before work on the task can begin.

Acceptance criteria

Acceptance criteria are a list of criteria that form your shared understanding of what it means for a task to be “complete”. A developer will likely use the acceptance criteria as a todo-list for building the feature in question. They’ll then check against the acceptance criteria to confirm that they’ve completed. The acceptance criteria can then act as a guide for you to give them feedback.

The acceptance criteria are the result of a conversation that you and your developer have about the task at hand. This conversation can start with you writing a list of acceptance criteria and the developer giving you feedback on them. You can ask the developer to write the acceptance criteria for a task and give them feedback instead if you prefer. Developers can help you to discover edge-cases and implications you haven’t thought of when writing acceptance critiera, so it’s highly inadvisable to write them on your own.

Here are some things your acceptance criteria might define:

• How the task will change the behaviour of the software for each defined user role.
• Whether the desired feature should match a given wireframe.
• What cases the resulting functionality doesn’t need to address at this stage.

Bringing task definitions together

Here’s an example of a task definition with all of the above-mentioned parts:

Comments on blog posts

As an anonymous user, so that I can express my opinion on a blog post, I want the ability to leave a comment.

Acceptance criteria:

* Anonymous users should be able to add comments at the bottom of each post (see attached wireframe).

* Comments should display in reverse chronological order under each post

* Comments cannot be empty.

* Comments cannot contain more than 1000 words.

* Registered users should be able to disable comments on their blog.

* Registered users should be able to disable comments on a particular post.

The end result of your requirements gathering should be a set of task definitions in roughly the format described above.

However you decide to define your requirements, here are the most important things you need to do:

• Note down the various features and tasks that you intend to have developed.
• Discuss them with a developer, preferably the one who’s going to develop these features.
• Capture the details of the specification that you agree on with the developer as acceptance criteria.

Task Decomposition

Remember that your goal is swift forward movement on the project. That means getting as much of your software shipped as quickly as possible. You want your developers to deliver the functionality as they work on it, rather than in one big release at the end of each week or month.

To do this, we need to take the requirements we documented as task definition and break them down into the smallest possible pieces of functionality that can be delivered individually.

Let’s consider our example of adding comments to blog posts. We can start by grouping the related acceptance criteria together, and then seperate the tasks out into their own definitions.

• Comments on posts

As an anonymous user, so that I can express my opinion on a blog post, I want to be able to leave a comment.

Acceptance criteria:

Anonymous users should be able to add comments at the bottom of each post (see attached wireframe).

Comments should display in reverse chronological order under each post

• Comment validation

As an anonymous user, so that my comments on posts are well formed, I want any comments I enter to be validated

Acceptance criteria:

* Comments cannot be empty.

* Comments cannot contain more than 1000 words.

• Comment configuration

As a registered user user, so that I can decide whether or not to allow comments on my blog, I want to be able to turn comments on/off across my blog or on a per-article basis.

Acceptance criteria:

* Users should be able to disable comments on their blog.

* Users should be able to disable comments on a particular post.

These were all part of one task to begin with and are now split into three separate units of work. Smaller items of work are easier to schedule, easier to reason about and can be delivered independently of each other.

Summary

Once you’ve got a broad understanding of the goals of your project and a developer in line to start building it, it’s time to specify the first few features of the project in detail. Tools for doing this include:

• Wireframes
• User roles
• Task definitions, including names, descriptions and acceptance criteria.

Once you have your initial requirements specified as task definitions, you can break those definitions down into smaller tasks to make the work easier to swiftly deliver.

At the end of your initial planning and requirements gathering activity, you should have a list of tasks that both you and your developer agree are ready to start. With clear requirements set, your developer can now focus on delivering the best implementation possible.

P.S. We’re Happy Bear Software. If you’ve read this far then you should probably sign up for our mailing list to get regular updates from us. No spam, and you can unsubscribe at any time.

Originally published at www.happybearsoftware.com.