Why user stories are important to developers

As a back-end developer at a digital product studio, I often get asked to implement new features without a complete picture of what problem the feature is intended to solve or how it is planned to be used. Often, these details begin to emerge towards the end of the development or in UAT, at which point it often means a lot more work (and cost to the client) to make changes.

Often, they simply don’t think about it, assuming that I know their business as well as they do but on rare occasions, I have known clients to actively withhold such information on the flawed assumption that I don’t need so much information to write code.

This often leads to the client receiving a feature that is, at best, only partially what they expected and, at worst, not fit for purpose. In many cases it also means that the feature does not fit well into the client’s long-term roadmap, resulting in costly rework further down the road.

How to write a good feature specification

Writing good feature specifications can be a valuable skill for a project manager but I believe that clients need to be the driving force in most feature development and the better a client can write their request the better the outcome will be.

Start with a high-level description

Writing high-level descriptions can be challenging. As a minimum they should include:

• Who is the feature for? Who will use it?
• What problem is this feature solving?

I find that using the following format works well at this stage:

As a website visitor

I want to set my contact preferences

In order to avoid receiving emails thatI don’t want to see

This “As a… I want… In order to…” notation helps to focus the feature writer into thinking about the purpose of the feature they are asking for. It can also help to avoid over-speccing a feature request by ensuring that each distinct feature gets its own spec.

Next, move on to detail

In the detail section of the specification, you should provide enough information for the developer to fully understand what the use-cases are.

A good way of doing this is to provide scenarios. For example:

Scenario: A logged in user accesses their contact preferences.

Given that I am logged in as a website visitor

When I click on “My Account”

And then I click on “Contact Preferences”

Then I should see a checkbox for “Recieve updates by email”

And I should see a checkbox for “Receive updates by SMS”

This structured approach to scenarios is known as Gherkin Syntax. There are more structured elements and keywords that can be used and it makes the features form a kind of living documentation that could be turned into automated tests.

Each feature should contain multiple scenarios. Don’t just include the straight-forward, common ones either. Include any outliers or “edge cases” too. Things that are uncommon but do happen, especially where they cause issues when they do happen. These will help to flesh out the developer’s view of what you are trying to achieve.

In addition, it can be helpful to include scenarios to demonstrate what the feature does not do.

Finally, write acceptance criteria

At this stage, you need to create a simple concise bulleted list for each feature. Each item in the list must be true in order for the feature to be considered complete.

Once you've written these, compare them to the scenarios in the feature. If there are any acceptance criteria that are not covered by a scenario you should go back and add scenarios as needed.

These acceptance criteria will be used as a checklist to determine if the feature is complete. The scenarios establish context and criteria that can be tested.

A note on automated testing

Automated testing can come in many forms. Using the syntax above can make writing automated tests simpler, however, you must also have sufficient time and budget to allow the developer to build automated tests.

This can seem like a large investment up front but the future benefits you will reap are well worth it:

• Preventing future changes from breaking earlier functionality (the already existing tests would fail)
• Living documentation — the features and scenarios match the functionality and provide documentation for future developer onboarding and could even be used to train new users.
• Allows incremental improvements — by tweaking and refactoring the code you can get some great performance, security and user experience benefits. The tests ensure that you don’t introduce bugs that break functionality.

As always, automated tests can only do so much. They won’t pick up errors that they are not coded to detect. However, when you find a bug you just need to write a new scenario under the relevant feature, get your developer to write an associated automated test, then fix the bug. Doing it in this way will eliminate the possibility of the same bug recurring in the future since the test will live on.

In summary…

Writing better specifications and giving your developers the complete picture will help you to achieve better results in your projects and also help to build a great relationship with your developers. Happy developers will be more productive and can even come up with some great ideas for improving your systems if given the chance.