How to write a good agile software specification?

What makes a good (agile) software specification?

First things first, let's see what a software specification is and what goes into it. A software specification is a collection of all information necessary to deliver the right software. It consists of several documents:

Software requirements describe the background, business goals and constraints of the project. Generally this is done by the client, or together with a software consultant.

Imagine the process of building a house. First you write down your vision, how many rooms and what features you want. These are you goals. The specifics of the plot, and the building laws are your constraints.

The software design document is a technical document that provides a precise solution to the goals described in the requirements. This includes data design, architecture design and low and high fidelity interface designs.

Think of this as the actual house plans: floor plans, foundation plans, elevations, section cuts, materials, electrical and plumbing schematics and so on.

Test documentation is also part of the specification. This document describes how, where and when the software needs to be tested, includes tests cases and associated risks.

These might be your housing quality standards and inspection documents, which ensure that the house works and functions properly, and will do so for the foreseeable future.

Last, but not least, there is the user documentation. These are written after development, but could also be considered part of the specs. User documentation simply describes how the software should be used.

We're agile, we don't do specs!

In the waterfall and V-models, to ensure the quality and timely delivery of a software product, you needed to create a down to the last detail software specification. But spec'ing out every element of the software takes a lot of time and is costly.

It's also unrealistic, because users are rarely capable of detailing every functionality they wish to see in the final product, so the scope of the project is bound to change countless times.

But what if we're using agile methodologies on our projects? A lot of people believe that agile teams are working without a specification. That's not entirely true. An agile project still needs structure, so nobody makes critical assumptions. This structure is given by the users stories, which are natural language descriptions of one or more features of a system, written from the perspective of the end user.

Agile is built around the principle that project scope can and should change during the project. All user stories will be placed in a backlog at the beginning of the project, but will not be drafted out in detail. Instead they will be shaped throughout the development process.

User stories should always be written from an end user perspective
User stories should always be written from an end user perspective

The agile process

Agile teams work in short (1 or 2 week) iterations, called sprints. At the beginning of each sprint, a small set of user stories will be picked from the backlog (usually those which add the most business value), and are drafted out.

Contrary to the traditional method, the responsibility of drafting out the details is shared by the client (through his product owner) and the development team. For this to work, everybody involved needs to have a shared understanding and empathy of the target customer. Because of that shared understanding, the product owner can focus on high-level requirements and business goals and leave all implementation details to the development team.

Example of a detailed user story
Example of a detailed user story

At the end of the sprint, feedback is given on actual working software, not just specifications. This allows the client to see if the product is aligned with his expectations, without having to wait (months) until the whole software is developed. If at this point, the client has change requests, they can be introduced as new user stories into the backlog, and planned into one of the next sprints.

Agile's flexibility allows changing the scope of the project along the way, as opposed to the traditional method, where it can only be done at the end of development, often by bulldozing and redoing months' worth of work. That of course, comes at a high cost, missed deadlines and not least, a drop in morale for everybody involved.

So how do we do it?

Let's get to the specifics, and tell you what we do here at C4studio. There's two types of clients we get. Those who already have the software requirements, and those who only have a short project brief or an idea in their head. Neither is usually from the perspective of the end user.

So the first thing we do, is sit down with the client's product owner, and create a backlog of all the user stories we can come up with. Then we categorise them into 'must-haves' and 'nice-to-haves'. Based on this backlog our team can give rough estimates on cost and time.

One extra thing which we sometimes do before project kick-off, is that we create just a couple of wireframes for the more complex interfaces. This is inconsistent with agile practices, because it creates a detailed spec well-before development, but we find it helps our team create better estimates.

A neat thing we do, is overlapping design sprints and development sprints. After sprint planning we do a design sprint, where we prepare the actual specifications (design documents, test cases, risk matrices and wireframes or high-fidelity prototypes) for the selected user stories.

At the end of sprint, we demo these to the client, and after approval, we start the development sprint, or coding if you will. In parallel, we already start the design sprint for the next phase. Because the team who does the development, already has all the information from the design team (UI designers, software architects, QA engineers) this method speeds up things by quite a lot if you have the right resources to do it.

That's a wrap on this article. We're always eager to find out about how others work, so if you'd like to share or have an idea of how we could improve our workflow, just drop us a line.

Want to hire us or just say hi?Get in touch now

We’re always willing and ready to listen to any request. So, if you like our work and you’ve got a project you want to discuss, just grab your phone or keyboard and contact us.

Company details

C4WEB STUDIO SRL Company no.: J35/2534/2013 EU VAT: RO34548173 CIF: 32329797