Skip to main content
Co-Founder. Editor, Research & Knowledge Sharing.
Feb 23, 2017

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.

“In my 7th session with the Devportal Awards, I strongly resonate with the user expectations for a decluttered, cognitively accessible, multimodal experience, with all information ready to be served just at the asking. Clear information architecture, effective search, and frictionless onboarding should be table stakes by now. With AI tools, these can be spectacularly augmented, as long as the extensive foundation is there.”


Laura Vass is co-founder of Pronovix, and organizer and host of the DevPortal Awards and the API The Docs event series. She researches trends and best practices in developer portal focus areas. With a master in Chemistry and academic studies in Functional Genomics, her interests include but are not limited to complex system dynamics, socio-technical systems, and conflict mediation.

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe