Explore the tools, processes and challenges documentarians have in an agile development team
5th December 2016, London UK
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.
Content Strategy Director at Worldpay
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.
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."
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.
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:
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.
Technical writer at Lavastorm
There are 2 scrum developer teams at Lavastorm and Emma is the one technical writer.
Tools:
Challenges:
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.
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.
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.
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."
Technical writer at contentful.com
Chris wrote about these fields in more detail and gave coding snippets too on Codeship's blog, see the links.
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.
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
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.
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.
Technical Writer
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:
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.
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).
Develop writer's processes to get control.
Technical Writer
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:
Works less well:
Agile is not the perfect solution but it has its advantages.
Original recording of the meetup by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0
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.