AGILE THE DOCS

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.

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."

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.

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.

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.

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."

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.

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.

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.

Agile documentation & prototyping at HM Revenue & Customs

Lee Hawksworth

Technical Writer

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.