Working software over comprehensive documentation

We've always found it pretty easy to buy into this, so much so that it rapidly becomes a truism, after all, working software is what your sponsors and users want, right?

We'll gloss over the faith-crimes committed under this tenet, projects with deliberate no-documentation policies, assertions that good test coverage is, in itself superior to documentation simply because it demonstrates working-ness.

Let's hurry past the minor sins of omission justified by misreadings of this article. Very few people like to write docs, and not as many people read 'em as maybe should. There's a lot of laziness hiding under misreadings of this item.

Let's focus instead on "Working Software".

Deciding whether a piece of software is working or not turns out to be a really problematic area...

• If you're building a client for an api which doesn't yet exist can you say it is working?
• If your approach was wrong and you've built an implementation which you intend to discard is that working?

Imagine for a moment that we scrub out "working" and replace it with "useful". Immediately our problems above make more sense.

Sometimes attempts to control the definition of "Working Software" can be surprisingly illuminating.

Here's a situation:

There's a feature, and it has a user story, in the conversations which formed the user story folk were exemplary in not smuggling implementation instructions into it. The story looks good, resilient. It captures a user need, and couples it to a business objective - most people who read it understand it and can immediately suggest a couple of different ways to fulfil it. Perfect.

At this point someone remembers to add some acceptance criteria, or a definition of done, or somesuch. There's an obvious moment of danger here, the story wasn't prescriptive, but it is much easier for prescriptions to creep into acceptance criteria. But it might be that adding the acceptance criteria at all was the danger. It is hard to write good user stories; writing good acceptance criteria is harder still, since they approach functional specification - which as we all know exists in a quantum state fluctuating between impossibility and futility.

Next off some development gets done, some snags arise, approaches are attempted and discarded, conversations are had. All good.

Later some testing gets done. And the feature doesn't pass for all sorts of reasons. Some of which are that the acceptance criteria have failed to keep pace with the rate of change in the approach to delivering the story.

So how many things are wrong in this picture?

What is happening here is a fine example of ritualized "agile" ceremonial.

Envisioning an end state, in this case in the form of acceptance criteria, has contributed this team's return to the false comfort of counter-revolutionary departmentalism. Within the lifespan of this user story there has been a reconstruction of the old scheme - requirements were gathered, a plan was made (which would have looked very old fashioned if we'd not been distracted by the fact that it omitted every thing between A and Z) and then the work was pushed from analysis, to development to test in a micro-re-enactment of the broken waterfall sausage-factory. The development of the software was driven by documentation... just incomplete documentation.

That the testing specialist was unaware of the changing landscape of the story suggests that the team hasn't understood what inter-disciplinary can really mean and is still organizing itself by specialization and processing tasks according to the logic of the waterfall - that one stage cannot begin until a prior one has completed. Imagine that this team had reformed their notion of "working software", that they had set their cap at usefulness rather than compliance. Imagine that they had included the test specialist in all the conversations around the feature. Imagine that the tester had been given the authority their expertees merits, to evaluate the software against the user story without their approach being prescribed by a prior department. Imagine, in fact, that the program of agilism in this team had fully corrected (by which I mean effaced) the uneven power relationships which tend to assert themselves when we relax our vigilance.

It is worth recalling here that we are reading a manifesto. A properly politcal document which aims at fomenting kaizen-revolution. A process which is necessarily incomplete if vestiges of old-think are allowed to shelter underneath rituals and mystifications.

"In order to ensure that user stories are subjected to sufficiently critical thinking I encourage teams to use the variant form:

As a <user type>, I want <function> so that <benefit> . AMEN

" (Anonymous sage 2015)

So, "Useful software over comprehensive documentation". Good.

While we're here lets fix the timing problem which can seduce us into reactionary thoughtcrimes, and at the same time we'll remove the stone under which anti-documentarianism born of laziness can hide.

"Useful software before comprehensive documentation". Right.