Long-term, agile documentation of requirements

In my training courses, we discuss many topics, including: how to document requirements in the long term, in an agile environment?

Documentation is stored knowledge. As things are forgotten, the value of documentation tends to increase over time. That’s why I think the question of long-term documentation is interesting.

I’d like to start with two options for long-term documentation that don’t make sense in an agile environment. Then I’d like to point out sensible options. Each with advantages and disadvantages.

It does not make sense to specify all requirements in detail in advance. In a complex environment, there are frequent changes. Requirements are re-prioritized. This is one of the advantages of agile development. Some requirements are considered, but never implemented. Or not as planned, because you gain new knowledge during development.

Discussion and documentation of a requirement costs time. If the requirement is not implemented as documented, it was a waste of time. Time that is urgently needed in development.

Let’s say you start to work in an agile way. Maybe you think: there isn‘t any detailed specification. But a backlog. Let’s use it to document the requirements on a long-term basis.

But a backlog serves the future, not the past. It’s more like a to-do list. What do we implement next?
The backlog is not a sensible option for long-term documentation. It doesn’t document what has already been implemented.

In a training course, a participant told me that his company manages user stories in JIRA. The developers archive them after implementation. Of course, you can search this archive. The participant reported that it worked well for them.

An agile pragmatist can hardly disagree. What works, works. At least in a certain context.

I see 2 risks of this approach:

  • Too many details: In order to be able to use the stories in the long term, you certainly have to document many details. What if the details cannot be implemented as planned? Will the user stories be adjusted afterwards? The stories may no longer document the implementation correctly.
  • Delta documentation instead of system documentation: User stories describe what needs to be done. The “delta” from one state to another state. In order to find out the current state, it may be necessary to analyze several past user stories. Stories lack context information. They are not system documentation, but only small fragments.

The requirement documentation can be maintained continuously.

Specifically: During a Scrum Sprint, you document the current state. The requirements that have just been implemented. The documentation grows over time. It is supplemented incrementally.

If you follow this approach consistently, it has a great advantage. The system documentation is always up to date. It documents which requirements have actually been implemented.

One challenge with this option is discipline. Only if you document consistently, the documentation will remain up-to-date. And that costs time.

Moreover, not every developer is a born documentation writer. If, however, the developers do not document themselves, but instead delegate it to other employees, then there is a risk of information loss.

One way to promote this discipline within a team is to put it into the Definition of Done. Something like: “System documentation has been updated”. To be checked in Sprint Review.

A completely underestimated type of long-term documentation is the code of the software. If you structure code appropriately and use naming conventions, you can generate documentation from the code.

To simplify this, I have developed a library. With it you can specify executable Use Case models in the code. They act similar to a state machine.

Here is a code example for a Use Case for a credit card:

The documentation generated from this code looks like this:

Use Credit Card

Assign limit: User requests to assign limit. System assigns limit.
Withdraw: As long as account open: User requests withdrawal. System withdraws.
Repay: As long as account open: User requests repay. System repays.

After Repay:
Withdraw again: User requests withdrawal. System withdraws.
Repeat: System continues at Withdraw.

Close cycle: Handles RequestToCloseCycle: System closes cycle.

Anytime, when limit already assigned:
Assign limit twice: User requests to assign limit. System throws assign limit exception.

Anytime, when too many withdrawals in cycle:
Withdraw too often: System throws too many withdrawals exception.

The same code controls the application behavior and is the source for the documentation.

The advantage is obvious: You can generate documentation with little effort. And it reflects the actual behavior of the software.

Of course, this approach also requires discipline. Especially on the side of developers. Before using any approach, you should try it out. Is it suitable for the type of software being developed?

In addition, you can’t achieve completeness with such an approach. For example, you can’t just generate quality requirements like robustness from the code. Design trade-offs are not part of the code either.

I am looking forward to your feedback. Which options for long-term documentation do you use?



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store