Build Living Documentation not just Software Requirements

Whether it’s a website, mobile app, or a large-scale software system, the traditional approach to software delivery goes something like this…

1. Requirements - Gather requirements from stakeholders and end users. Document these in a document or project management tool.
2. Plan project - Using a project management tool for coordination, break the requirements into small tasks and deliverables.
3. Develop project - Developers reference the tasks, and communication and changes are usually via those tasks. Naturally, everything goes perfectly, and exactly on time 😉
4. Test project - This usually happens during development also, referencing the project tasks, testing they do what they should, leaving comments if issues are found, and repeating the process until everything is ready to go.

Agile development repeats steps 2 to 4 many times as “sprints”. But no matter the frequency, this process is common across the industry.

There are bugs in your requirements

During testing, it was found that the registration form allows users to signup with their country specified as “USA”, but the phone number entered does not match the US telephone number format. This is deemed a bug, as the business wants to ensure valid countries and phone numbers are entered. If not, the user should receive a nice little error message letting them know of this mistake.

However it’s not a bug in the software, it’s actually a bug in your requirements because the developer was never told this, and in truth, no one had ever thought of it until now.

And that’s fine, this happens all the time. We simply leave a comment on the task requesting this change, or possibly create a new task “Ensure countries and phone numbers are valid on registration”.

Problem solved, everyone's happy, and the world keeps turning.

Project management tools can dissolve your knowledge

As software grows, new features come in, and new people are involved - knowledge gets lost. And vague memories of how all the different features work start to dissolve, as your head pushes new information on top of it.

The fact that the phone number validation on the registration form relies on the chosen country slips out of people's memories, and the Jira sprint that contained the task is long closed - and no one knows where Jira tasks go once the sprint is over 😆

One day the CEO decides that the “Country” field is not needed on the registration form, and removing it will reduce the friction of user signups. The product owner then adds the task to the next sprint.

The developer makes the change, submits the pull requests, gets approved by her technical lead, and merges in for testing. The tester confirms the “Country” field has gone, and due to being rushed and at the end of the day, they didn’t test submitting the form.

The automated backend tests passed, and everything seemed fine - so the sprint was deployed.

No one, not the CEO, the product owner, the developer, her technical lead, or the QA tester - remembered that the Phone number field relied on the Country field.

The impact was as soon as you entered a phone number, the registration form broke, and you couldn’t continue.

No one could sign up, and people were mad (including users, but also the CEO!).

But how could this have been different?

Turn requirements into documentation

Arg, people hate the word “documentation”, and I do too.

But let’s go back in time to the start of the project, and see how this could be avoided without doing any extra work.

1. Instead of capturing requirements in a Google doc, they could have been captured in a requirements management system like Userdoc.
2. These could then be easily synchronized with Jira, actually saving time creating all those tasks
3. When the requirements bug arose, and it was found you could enter invalid phone numbers that did not match your country, instead of leaving a comment on the Jira task to add this in, the original requirements should have been updated in Userdoc - with the “User Register” user story having its acceptance criteria updated with “Phone number format is validated against the chosen Country”. This is easily synchronized with Jira again, and the developer implements it.
4. When the CEO asked to remove the “Country” field from the registration form to improve signups, the requirements were again updated in Userdoc instead of directly in Jira, but this time it was made obvious that removing this field, would impact the phone number - so the product owner ensured they removed this requirement too and communicated it to the developer.

None of this is magic, and in fact, it’s no more work than any other method of communication.

It's a byproduct of keeping your requirements up to date, and then synchronizing with your project management tools - means that you always have a constant source of documentation - living documentation - that the team keeps up to date.

A puppy isn’t just for Christmas, and requirements shouldn't just be for the start of your project.