Fit for purpose documentation

One of the many myths about Agile, is that the Agile team do not do documentation.

This is not true.

[[as I ouline here [[xxx]] doco is down right and at the right time]]

As well as ensuring the documentation is done by the right person and done at the right time, we also need to ensure it is done for the right reason.

I use the concept of ‘fit for purpose’ to hep clarify the reason for the documentation and what should be documented.

It starts with the simple question of :

“Who will do what based on the documentation”

So what is its intended use, what do we expect somebody be able to do after accessing the documentation and more importantly what do we expect them to not do.

So examples:

As Built Doucmentation

[[lets somebody have the big picture]][[they can easily find where things are]][[they don’t have to ask lots of people]][[it doesn’t contain code, code wil change and they should be able to read code, they just need to find it]]

Design Documents

[[if it’s in a modelling tool, point them at the tool]][[make a high level doc that provides context, aka text, of the data model.  Don’t make them ask somebody]]

Release document

[[purpse of doing the release]][[purpose of approving the release, ie Change board]]

{{There is of course still the idea of the wrong kind of documentation, done at the wrong time.  This is documentation that does not add value, is done to early, or is done in such detail that the effort to produce it far out ways the value it delivers.

An example of this was for a project where the organisation was running Agile projects, but also had a strong waterfall based Project Management Office.  This as you would expect caused a large amount of tension between the the two delivery styles.  In the planning sessions the Scrum Master would let the team evaluate the backlog, score the effort and pull the applicable user stories into the sprint, following the AgileBI approach. However in the same planning session the Project Manager would be trying to mandate milestones and deadlines, as well as try to mandate what stories should be done next.

In one of the planning session the Project Manager mandated that a naming standards document should be created first.  This wasn’t such a problem as there was no such document, and by defining it early the team would reduce the risk that they would have to rework their code to meet new naming standards in the future.

The acceptance criteria for this document were weak, however the team time boxed the effort as a way of ensuring it was achievable in the sprint and that it didn’t consume a large amount of the teams time.  They of course delivered the naming standards document as done done in the sprint.

However in the next sprint the Project Manager demanded that the team create another document that listed all the documents that they had created, what they contained, why and how they should be used.  Not just a list of documents, but a document that provided summaries of al the documents.

For me this was overkill.  I could potentially see the need to create a detailed catalog of documents near the the end of the sprint iterations if it was required as part of the organisation formal release process (it wasn’t).  Or potentially to provide a catalog to enable quick access during BAU by people outside of the sprint team to understand the impact of any changes or where to make them.  However in that situation I would have suggested a Wiki or some other form of visible solution for cataloging all assets the AgileBI team delivered.

The team could easily leverage the value required from the current documentation by having a quick conversation, rather than trying to find the documentation that listed the documentation.

This issue of course highlighted a number of other problems with the Agile approach being used.  The Project Manager was determining the stories to be delivered, not the Product Owner.  The Project Manager was determining what should be done next, not the developers.  The Project Manager was mandating when a task should be done by.   All of these are indicators of “doing agile” not “being agile”. }}