Should Documentation Be Part of the Definition of Done?

The UK kernel of the Write The Docs community together with the Government Digital Service held a one-day mini conference on the practice of agile documentation.

In his presentation Rob Woodgate gave us a half-hour distillation of his insights on where technical documentation stands with agile development methods. He wrote several articles in the past years on the mythical nature of the multi-talented developers, around the definition of done and the situation of doc writers in a scrum development team.

“I’ve seen very few teams that are actually agile, where everyone is able to work on stuff all in the same time, where you get up and down in that circular effect. It does tend to be a series of mini-waterfalls.”

In theory, everyone in the scrum team pitches in to every task, thus allowing the incremental delivery on time and quick reiteration. But in reality technical writing is a skillset and mindset apart.

“If only the designated technical writer can produce the documentation, you’re a single-functional team. Bear in mind that adding an additional writer won’t make you semi-functional, because documentation can’t complete until testing completes, so adding another writer will give you more manpower, but it won’t change the inherent problem that software development is a linear process.”

Scrum or no scrum, there is still the accordion effect squeezing the time left for documentation.

Can we ship the docs together with the working product or only expect them later? Depends on the context. Rob gives us a clear 6-steps algorithm to see if we have enough in our favour to venture the docs into the deliverables. The detailed explanation serves

A/ as discouragement from ever again doing so; and

B/ once we get over that, use them as checkpoints towards changing our team’s inner workings.

“… it lies in the culture of the company. If everybody in the company has the ability to do continuous improvement, then you have a much better chance of seeing it work. Where people work together to get stuff done because they understand it to be the goal. But what tends to happen is people will go like, ‘Let us do agile!’ and the dev teams are gonna be scrum teams and nothing else changes… it’s a complete waste of time, it fails repeatedly… All or nothing.”

Recording of Rob’s presentation, presentation slides and his own notes to read

Video recording

Slides

Rob’s notes

Check out Rob Woodgate’s blog to see more of his take on the topic.

The WTD London community organizes monthly peer-to-peer meet-ups for documentarians. If you care about helping your readers have an awesome experience when they finally do read the docs, this meetup is for you. If you want to meet with other people that have chosen this path in the London area, to share war stories or to get inspired, come and join us on one of the meetups.