Patrick Hammond - Let writers write: Automating the boring stuff for our docs team

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 4 November. We are honored to share the video recording, slide deck, and talk summary below. Enjoy!

Visit the API The Docs 2020 recaps overview to explore all presentations from 2020. API the Docs Virtual begins May 2021! CFP closes February 28, 2021.

Patrick Hammond

Project Manager - Doc Ops at Adyen

Patrick's presentation (video recording)



Patrick's slides



API the Docs Podcast

DocOps and Automation to the Delight of Technical Writers! - Interview with Paula Henk and Patrick Hammond (Adyen)



A journey toward DocOps

In 2017 first conversation about moving to docs-as-code/DocOps. Issues were that for almost every solution they had to use plugins, the fronted tech was unfriendly, the possible tools didn’t eradicate collaboration barriers, and most of them used unconventional documentation formats.

Now, at Adyen, the documentation team is managing 2000+ pages of documentation, having 1000 reused items for different audiences in a collaborative, central, crowd-sourced docs-as-code environment based on Markdown and Github. They are working closely with the CMS developers to have a convenient and useful IDE (integrated development environment) and they write their own extensions and tools to test and publish their docs.

DocOps involves facilitating a content flow that is collaborative, agile, continuous, enables reuse; it helped create a culture that serves documentation in a way that understands how techwriters work.

Their DocOps tools are about to keep the docs flowing.

Code samples in docs

Technical writers are frustrated by having to update:

  • lots of similar and small samples,
  • in separate locations,
  • in non-generic custom libraries,
  • across seven languages,
  • without testing.

Challenges

  • Buy-in and adaption: Maintaining code samples need to be easy more convenient for technical writers
  • Responsibility & ownership: Split between the program’s logic and what can be defined by technical writers
  • Testing: Many different gauges and environments
  • So much data

Steps to take

  • Analyze current code samples to determine patterns, variations, and inconsistencies
  • Gain agreement on how you want the code samples to look like at the end
  • Break down the code samples into chunks and separate them
  • Develop the logic to rebuild the chunks into code samples per language
  • Launch fast, iterate

Results

  • Improved samples, easier process
  • Consistency across languages and integrations
  • Single point of updates
  • All reused with variable content from one location

The future

  • Automated testing: From manual rudimentary testing to including the developers’ testing framework
  • More integrations
  • Simplified and more dynamic workflow, minimized redundancies, more libraries

Watch the video recording for a live demo.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.