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
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.
Laura co-founded Pronovix in 2005. She is Chief Editor of our blog & developer portals newsletter, a host of the API The Docs podcast and event series, and an integral force for connectivity and communication at Pronovix.
As a member of many teams she researches trends and best practices, organizes and reports on knowledge-sharing events in the API, DevRel and technical documentation space. Interestingly, Laura has a background in Chemistry and Functional Genomics.
Her interests include but are not limited to non-violent communication and mediation, the dynamics of cultural shifts, and localization. Knitting techniques and the point of mastery when one knits with the balance between space and yarn.