How to keep specifications up to date when features are updated?

Context:
We’re using Jira for bug/improvement/new feature tracking and the X Ray extension for test management. We’re using one Jira project for the first and another Jira project for the latter.
We have different applications in one Jira project as the codebase is shared (embedded software/small range of different hardware).

My question is how to keep specifications in Jira up to date when features change/are updated/are improved? For every version I hope to have an overview of the most important features our product should contain. How do you do this? Would you clone existing tickets when adding a new version to Jira and update the tickets where a feature has been changed?

I’m asking this because I hope to have a “single source of truth” that is more up to date than it is now and I really have the feeling of missing a structure now.

I tried Google but I’m not sure where to look for. I’m aware of the concept of specification by example however my fellow colleague engineers /internal customers are not aware of it. So it’s reallly challenging to implement specification by example.

5 Likes

The only way to do it without making it an extra chore (which eventually
will not be done, accumulate, and return to that state on which the specification is mostly useless), is BDD: Instead of updating the specifications when the software changes, you drive the changes in the software using the updates in the specifications.

4 Likes

The main concept for keeping something up to date is utility. If it is used a lot it will more likely be accurate, if it is not used it will be outdated. For instance using Code as your single source of truth have the highest utility since your product will not run without it. Might be inconvenient for some consumers to read. Which for instance is where BDD comes in. You write your code (in effect something more human friendly that gets converted to code) and you use that to check if the production code does what is described. High utility that is a little more accessible. But if it is not used by product owners or developers then the you are in a similar situation as before. Some other things that can be used is training material, user manuals or any other product documentations that you actually “sell” to customers.

2 Likes

Requirements docs are often not in one place, when new people join, they end up having to read all of the code, the wiki is just spaghetti. Nobody updates docs. Code is also a good source of truth, but it’s probably the worst place to go looking for requirements, because you will only find the defect of bad requirement interpretation and bad testing gaps there. There are many reasons for these issues, and simply buying another tool is not a solution, it’s even a small part of the problem. Ownership.

Lightweight and minimal documents, that are every-day use applicable. This makes it easy to remind a team at the end of every sprint to update documentation. It’s easy enough for a team lead to check the docs system’s logs or timestamps and work out who is not regularly making any actual document updates each sprint. People don’t want to own huge documents, keep it as small as possible, but keep it “living”. You basically want a way of “marking” documents or “organizing” so that it never overwhelms you.

3 Likes

Besides the excellent points which were already brought to the discussion I want to add 2 points just as input - maybe the might help you:
First: If you think it is applicable in your team you can do some research about the topic “docs as code”. The basic idea is to have the documentation in textform together with the code. The documetation afterwards is rendered in your pipeline for instance in HTML form. Speaking from personal experience this has helped a lot in regard of having a living and up to date documentation.

Second: Another interesting idea is the idea of executable specifications. The basic idea here is that you have executable tests which describe the behaviour of your application. I don’t think that this can be the only solution, as you might have stakeholders who are not able to read code. However it can help to keep your specifications up to date as your for example can refer in your documentation to this executable specifications.

@conrad.connected mentioned it already before: Ownership. This is really so important - if you don’t have one person in charge your specifications will most propably not be up to date. A short reminder: Ownership does not mean that this person is the only person working on the documentation, just that this person ensures that the documentation is updated.

2 Likes