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

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.