Documentation in Agile Methods

There are still a lot of questions about how do we properly manage the documentation in agile methods? And the answer to be honest isn’t so simple.

Let’s start from the best known: modern Scrum

The differentiation between agile methods isn’t insignificant because if they try to respect one of the 4 values ​​of the Agile Manifesto, the interpretation of this sentence can easily differ.

Value of the Agile Manifesto:

“Operational software more than exhaustive documentation”

If we started from the user-story?

In the generality of Scrum projects, the teams start the documentation by the implementation of user-stories (practice coming from Extreme Programming).

What to put in our user-stories? Some teams develop applications from user-stories that fit on a small sheet. However, on a large number of projects, I fear that this practice have a lack of precision that can be expensive in the future: how to ensure management rules? How to find them later?

To ensure a perfect understanding of the user-story, it seems essential to feed it with the management rules, wireframe, test scenarios or even other complementary elements because there is not a perfect format.

Here is an example of format that I had presented in the past; you can find another format.

Story A4: effective user-story format

The user-story really enough?

Small sentence that I heard in the past: “the agile says no exhaustive docs so we do no documentation …”. The interpretation is simplistic and far from the idea of ​​the agile manifesto; the trouble is that some people read the beginning of the sentence “Operational software more than” to understand the whole philosophy on the subject.

“More than” means that we don’t exclude the documentation (even exhaustive if we go to the exaggeration of the interpretation) but that the software is preferred. In fact the documentation will create from the software and not the opposite; it’s different with the project management methods such as Cycle V or other waterfall. Unlike the scrum, some agile methods make so-called essential documents before development (but no exhaustive documentation)

In some contexts, the user-story is not enough because its historization can quickly become a real puzzle.

In fact, in agile, you can create complete docs or you must not deprive yourself, but often after development. Making documentation after development brings the documentation to be much closer to the product done.

You may need to have technical documentation of the product’s technical foundation, user documentation, and functional documentation. Do not deprive yourself of it, it would be a mistake.

Only the necessary documentation

Documentation in the agile world is incremental; a project improves with the feedback of customers so we do the documentation in just-to-time.

If this way of doing changes the work of teams, that doesn’t remove the need for documentation essential for the sustainability of the product. Unlike project management methods such as the V-cycle, it is necessary for a project to see its documentation build during his progression because otherwise a part of it will be a waste of unnecessary time.

Make KISS documentation

This is a tip that I give you; don’t hesitate to simplify as much as possible your documentation in order to go into this KISS philosophy (Keep it simple, Stupid) which can also apply to the documentation.

Simplifying documentation will have good results : it will be more easily to maintain, to offer the product more chance to evolve because the future members of the team will better understand it  …

For user-stories, the collection of user-stories by Epic (and by theme at the top level) can greatly help to simplify functional documentation as much as possible; this is even sufficient to be representative of the functional documentation of the product.

However this implies a very good breakdown of user-stories and the use of Epics and Themes (that story mapping really helps to manage).

Your functional documentation could be a Jira with the Story-mapping plugin simply. But without that, looking for the management rules on features in the future will be a real headache.

I can only advise you to use framing techniques to help you to handle this division as the creation of a story mapping to launch a project or to add features:

Story mapping, a clear understanding of its creation

And for the technical part?

For those who make the storyotype to embark on other requests than user-stories (often essential although too often forgotten) with requests of the type: technical task, spike, bugs … it will be very difficult to use them in live to document them.

Making user-stories of different storyotype

Knowing that the agility focuses its developments on the business value (for key users in a functional way), the technical part is completely unstructured in these documents.

I strongly advise to use a wiki or equivalent to make docs on the technical part; you have to be KISS with theses documents.

Be careful, this doesn’t prevent the documentation of the code so that the future developers can understand at a glance every part of the code. It’s especially in case of complex bugs.

What do some agile methods tell?

This part is more for your agile culture but the agile method that they’re not used in France. However, we can find very good things in them.

Remember, the Scrum doesn’t talk about initialization phase unlike other agile methods. For example, the DSDM recommends to make a Feasibility Report and a Global Development Plan during the feasibility study that are defined in the form of documents.

We don’t talk about exhaustive documentation but of documentation well focused on specific subjects.

In this method we also talk about the creation of the document called Definition of the Industrial Domain and the document called Definition of the System Architecture during the business study of the DSDM

As you can see, other agile methods are much more documentary than the Scrum or at least the interpretation that we wanted to make.

NO, agile methods don’t prohibit documentations, but they favor putting effort into the operational software and not in the documentation.

Conclusion Documentation in Agile Methods

I hope that this article will give you a better vision on the documentations in agile methods. There are probably other recommendations but I hope that the one I bring you here will help you in your projects.