Skip to main content

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.

Ben's presentation

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

Agile DITA

David Hollis

Senior Technical Author and DITA Information Architect
 

DITA: open standard for structured authoring Single source for multiple output formats --» flexible content reuse

Topic based structured authoring lets you focus on the information only. You can use topics to match the Agile sprints. Base reviews on topics (or bundles of them) and get reviewed continuously --» reduce the end-of-project review process.
Topics are also more likely to get a thorough review than the whole big document.

David's presentation

Be the Agile Creator!

Ken Davies

Technical Writer
 

Ken's slides

Talking further about the writer-developer interface, referencing Paul Adams' presentation at WTD Prague 2016 (The author's place in a scrum development team).

Problems:

  • Agile forces people to organically work together, this can become chaotic and unproductive.
  • The writer's work is not done.
  • Agile is development driven.
  • Developers have a lot more technology helping them in an agile environment (automated testing, CI).
  • With each release the doc-needs keep growing.
  • The multiple stakeholders want the information from the docs fast.
  • Writer has many integration tasks (chatbot, microcopy, etc).

Ultimately the writers fall behind with the tasks.

Suggested solutions:

  • Establishing the goals of the agile environment:
    1 Add value of docs.
    2 Add to quality of docs.
    3 Trust between writer and developer.

  • Write a plan for the author: specification, resources, deliverables.

  • Ask questions (and so develop trust in the group).
  • Dev vs Doc tasks, low - high priority. Developers can write too and writers can do non-writing tasks.
  • Accept delivery to be of small and different sizes.
  • Develop readiness:
    1 Have an iterative plan, what can you deliver half-ready.
    2 Build a schedule.
    3 Build locations for review and final versions.

  • Participate in the sprint plannings:
    1 UI design and wording ideation.
    2 Card sorting for how much effort is a task.
    3 Show results.

  • Keep scrum tickets for general circulation very simple and clear (don't add the subtasks that only you need to know).

  • Accept the rhythm of cycles: writer will fall behind but just keep asking questions and reprioritise.
  • Start production by bits, even if all docs aren't ready.

Develop writer's processes to get control.

Ken's presentation

Agile documentation & prototyping at HM Revenue & Customs

Lee Hawksworth

Technical Writer

Lee's presentation

Writing in Agile development environments

Andrew Westfold

Senior Technical Writer at Intel Security (formerly McAffe)
 

In the Agile manifesto: working software over comprehensive documentation. Understand as project documentation.

Andrew works with several teams in many timezones, all working in agile with some differences. They have many, completely different products with different screens and workflows.

"As a writer, the closer you can get to your teams, the easier that's gonna make your life. If you try being a standoff, 'Well you guys can work in agile and I'll just carry on doing what I'm doing', you'll have even more problems than you had back in waterfall."

Works well:

  • 3 week sprints, that leaves enough time for the documentation too.
  • "Having tasks (for documentation) within the (developer) team's stories means that the whole team is as committed to getting the docs right as I am, because if I don't get the docs right, they can't pass the story."
  • Every story has to have at least 2 reviews within the team.
  • A couple of development sprints are then rolled up into one release, which gives opportunity for a wider, whole document review too. At least development, QA, project owner review, then final editing cycle, then localization cycle.
  • Every product has a responsible UX designer who is tasked to finalize the designs ahead of the sprint - so the docs can be drafted from the design, but all draft docs are stamped "scrnshts will be updated".
  • For all new team members, one of their first tasks is to review the whole doc set written up to that point. They so gain somebody that has never seen these documents before can give feedback, and it is a part of on-boarding, giving the new colleague a reasonable understanding on how the products work.
  • "For story demos, lead with the documentation to explain from the customer's perspective what that feature does - then the developers can come and say how clever they were."

Works less well:

  • Documentarians trying to work a sprint behind.
  • Documenting feature by feature because you have to fit them together afterwards.

Agile is not the perfect solution but it has its advantages.

  • One disadvantage of agile is the amount of meetings it generates. Hopefully those meetings are shorter. If you don't need to attend them, don't attend them.
  • Daily stand-ups are probably the most important: if they are well run, they alert the whole team early on to what is stopping the achieving.

Andrew's presentation

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

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