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's 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

Challenges:

  • 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

Lightning Talk on Katacoda

Ben Hall

Founder of Katacoda, interactive learning environment for software engineers



Katacoda is a technical learning platform directed toward software developers, where the documentation is shifted to very real-world scenario heavy aspects. Start with a quick overview of concept, then drop people into a live developer environment. These are virtual machines hosted directly in the browser or configured as per the developer’s specific needs.

Third parties can embed the developer platform on their sites, and so have a more interactive tutorial where the technical preconfigurations are already done (and thus this initial barrier removed). Developers engage better.

They’ve built an editor that uses markdown and through a set of selections one can set up the environment to work in - but this was still a disconnect from the browser experience. They now use Github as an easy starting point for documentation (in markdown), this way allowing the devs to use their own usual workflow and tools and thus helping continuous delivery for tech guides.

Grammarly' automated suggestions helps reduce file changes back-and forth and generally reduce the editor's work.

Lightning Talk: Documentation Management Practices at IBM

Adrian Warman

Content Choreographer (Information Development and Content Strategy) Lead at IBM UK Cloud Data Services.



Within the software development group at IBM, the various teams use doc tools and techniques that reflect the rhythm of their product development process.

  • IBM's old style products with yearly release cycles can make use of traditional documentation tools.
  • As IBM acquired Cloudant, they not only got the product but its mindset as well. The documentation is written in markdown and stored on github.com.
  • IBM Graph is a hybrid sort of internal project using markdown and github.

Old established processes are very difficult to change and an outside developer is very unlikely to write documentation to an old-style technology. But in a never environment they are very likely to write initial contribution (and some cases full scale contribution) particularly to API reference documentation, less so to user guides. Projects using open technologies were able to get a lot more interaction both internally and externally, with daily or even hourly updates.

IBM's content creation process is changing: "technical writing" turned "information architect" turned"content designer". They receive beta-content from developers, marketing, sales, customers, which they then refine with the UX and the key message in mind.

Important but often omitted: Accessibility testing, video/augmented reality technologies. Written words are only a part of the user experience.

In the future: Emphasis on user experience, designing the flow, bringing together the different media types and expectations. Using the AI Watson to real-time analyze the support calls to determine the subject of the conversation and refer the user to the corresponding information resource. The tech writers are only helping Watson to help the user.

"As technical writers we are becoming content choreographers, ringmasters, guiding people through a rich customer experience."

Adrian's presentation

Continuous Documentation

Chris Ward

Gregarious mammal

Technical writer at contentful.com



Open source testing tools tips to assist continuous deployment of docs.

Chris wrote about these fields in more detail and gave coding snippets too on Codeship's blog, see the links.

Spelling, grammar

Markdown-spellcheck uses open source dictionary files. Adjust your script to your preferences (e.g. report mode, ignore numbers and acronyms). Create a separate repository with the typical custom language (not a real word, but not wrong), so they won't get flagged by the checker. Decide what to let through.

Atom editor with extensions

Write-good gives a report-like output, more of a guidance, hard to automate its evaluation. You can write different tests for it, e.g. weasel-words

Testing codes

  • Dredd for API examples (in Blueprint and Swagger/OpenAPI formats),
  • Inline code testing is a little harder, Sphinx can do it for Python.

Screenshots automation

  • Capture a screenshot along your successful selenium tests.
  • Idea: from your examples you could generate a json and make videos at a continuous integration. Works for examples from terminal.

Code examples and live code playgrounds

Languages like JavaScript or Ruby offer interactive possibilities with the documentation. E.g. JSFiddle lets you embed your JS and people can experiment with the output while reading the docs. Autogenerate the code, feed the results to a service with an API and generate the playground dynamically.

Chris's presentation

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