AGILE THE DOCS
Explore the tools, processes and challenges documentarians have in an agile development team
5th December 2016, London UK

Challenges facing technical writing

Rosalie Marshall

Technical writer at Government Digital Service UK

Early 2014: GDS had many products with documentation but no tech writers. What does good government documentation look like? Shall they use automation tools like Swagger or Raml? They were then still relying on their developers to write their documentation - but developers' priority is the product. Hired/hiring tech writers.

GDS follows the agile principles but they face challenges: the focus is on the product not the docs.

Challenge #1 is the approach that the product should be so good it should speak for itself, so we need no documentation. To promote docs, show user research that users do struggle and need documentation. Sometimes it's hard to translate user reseach data into a prioritized to-do list.

Challenge #2: the docs writers are only brought in when the product is ready. They loose data from middle of the developement process.

Solving these challenges by:

a/In different groups their tech writers integrate differently
PAAS, Ben: treat the docs as developer stories, end-of-week email to update on docs changes. Registers, Jen: not part of the dev cycle, watches out for pieces of work that might impact the docs. Verify and Notify, Cathrine: developer makes the docs changes and tech writer reviews the pull request.

Documentation is not part of definition of done in GDS. Open for opinions on that.

b/ Creating standards to assure users that the product is up-to-date, coming from a trusted resource and is accurate.
User research to create a template to target different users' information needs.
Documentation prototype format for developers within the government.

Keen to learn about how to make GDS content more agile.

Rosalie's presentation

The Worldpay shift from user guides to experiences

Stella Crowhurst

Content Strategy Director at Worldpay

Jamie Measures

Information Architect, global eCommerce at Worldpay

How they shifted from waterfall to agile user documentation in the past 2 years.

The too few technical writers would have to sit together with the development teams and keep the documentation always updated, sometimes even write it. 30-40 different projects every year, developer teams all over the world using various methodologies: time consuming and hard to plan.

"Working in an agile environment is tough: developers are very opinionated and sometimes they don't like to have a technical writer sitting there every day and asking questions."

Their key to succes was to really get control of the writing process and how they relate it with agile.
* Be more assertive and own the writing process.
* Inform developers what and when will be needed.
* Write only what is really necessary and focus on the persona.
* When the pressure is really bad, do co-writing sessions and/or workshops.
* Inside surveys, kick-off meetings with the project manager.

Decided to focus on developers' integration documentation, and give FAQ-style docs to support users with a problem.

"One of the ways we gain respect with what we've been doing is asking those brilliant questions that tech authors ask. [...] We genuinely influence the user interface design in a positive way. An extra thinking brain in the development cycle of the product, asking those innocent questions that developers tend to tunnel-vision away from."

Stella's presentation

and slides

Should documentation be part of the definition of done?

Rob Woodgate



For true scrum cycles we need fully multi-functional teams, which we don't really have. Also, software engineering is still a linear process and some part of documenting always falls to the end. Rob gives us a list of questions to help make a decision whether to still include documentation in the DoD.

See our blog post and Rob's own notes and links.

Rob's presentation

and slides

Agile Authoring methodology: Learning from Lean

Ellis Pratt

Director at Cherryleaf


Being lean is to keep the whole process, from beginning to end as efficient as possible. Not just the software development team. Divide work into single-focus tasks (automation), let anyone be able to stop the process in case of error (autonomation).

Identify waste:
* muda: not adding value to the user. Unnecessary content creation.
* muri: overburdening. Too difficult/too much work for the time given.
* mura: unevenness, waiting around. Delays in approval process.

There is essential waste too, for example quality testing.

Load balancing: get rid of over- and underwork, even out the workload. Bring in subcontractors for example - but they need to know the tools too. Templates help.

Docs as code: act as a content developer. Add the docs tasks to the Kanban board, refer in title to the coding reference numbers. Review and edit as if it's the calibration&defect of code.

Deliverables: just enough documentation at first sprint. You can publish docs in increments.

Optimise the whole: make people aware of the costs of documenting late, where that might generate waste.

Lean and agile methods spotlight process problems, so you do need a commitment to resolving those.

Ellis' presentation

and slides

Bringing agile to technical documentation at Lavastorm

Emma Hughes

Technical writer at Lavastorm

There are 2 scrum developer teams at Lavastorm and Emma is the one technical writer.

Tools:
* Legacy docs were all in Word/pdf, switched to MadCap Flare, publishing integrated HTML help * Integrate with Perforce * Slack - makes docs life visible, also gives peek into what the developers are up to
* JIRA - task tracking on separate docs Kanban board but the devs mark need for docs-writing on their JIRA tickets * RealTimeBoard - using the devs' tools

Challanges:
* Balancing her time between processing their legacy documentation and writing up new developments. * Only attends relevant scrum meetings but checks highlights.
* 2-weeks sprints. Docs are not part of the definition of done, but unofficial agreement on keeping the docs up-to-date. * Work with UI team to keep ahead.

Emma's presentation

Tempo - an alternative reason for agile

Kristof Van Tomme

CEO at Pronovix

Frequency is a function of time: it is essential for change.
Observe the changes in tempo all around us: teams also have their rythm.
Be sensitive to the tempo of the group, you can modulate it to your benefit. (see 'Tempo' from Venkatesh Guru Rao) As in FM, we need a carrier wave in a company: the agile process sets this steady rythm and each smaller team can resonate with it.

Kristof's presentation

Original recording of the meetup by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0