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


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.

About the author

Laura Vass

co-Founder. Financial Manager. Editor.

Co-founded Pronovix in 2005.

In daily operations Laura is editor of our blog & developer portals newsletter, interfaces sales and marketing, besides creating and holding spaces inside and outside our team.

Specialized in developer portals, we research trends and best practices, organize and report on knowledge-sharing events in the API, DevRel and technical documentation space. We publish our recordings and quick-parse recaps of presentations on these events, and write our own findings and suggestions published on the Pronovix blog.

Pronovix is an active member of the Drupal and the Write The Docs community. Laura is co-organizer of the Amsterdam Write the Docs meetup groups and of the API the Docs conference series.

Latest interests are non-violent communication techniques and mediation, the dynamics of cultural shifts, localization. Knitting techniques and the point of mastery when one knits with the balance between space and yarn.