We got into technical writing to make complex things seem simple, not to be janitors. So why do we spend so much of our time on maintenance? We fix broken links, find missing images, remove sensitive information... and that's only if we know these problems exist! Worst of all, we manually create and update code samples. Broken code samples are useless at best, and downright maddening at worst. Developer experience is really important to Adyen, and we got sick of seeing code samples become inconsistent and inaccurate.
In this talk, Patrick Hammond will explain how Adyen approached the problem of creating, updating, and testing code samples. He'll discuss the solution they created, and how it works for their team. He'll also delve into some other common bugbears that Adyen are automating away, much to the delight of their 8 technical writers.
7. Things we hated
There were many more, but this slide has 4
boxes.
Plugins & control
Plugins, plugins everywhere. Docs in weird
format.
Collaboration
More. Plugins. And more barriers.
Frontend
Plugins, and unfriendly tech.
11. What we use now
We are happier people now.
Collaborative, central, crowd sourced
Docs-as-code with markdown in Git.
Robust quality and delivery
We wrote tools to test our docs and built our own
publishing pipeline!
Customizable CMS
We work closely with the CMS developers, and
write our own stuff where needed.
17. Lots of similar samples,
and thus lots of
repetitive updates.
No testing!Non-generic custom
libraries, across 7
languages.
Writers update 140+
samples in separate
locations throughout
docs
Code Samples
So many samples, so little time.
18. Janitors
A noble job
Extremely necessary in the physical world
Keep everything clean and tidy
Keep everything working and ready to go
Usually not technical writers
19. Technical writers
Not janitors
Want to be able to write
Have to perform many additional supporting tasks
Don’t want to maintain hundreds of files
Don’t want to repeat themselves
Varying levels of familiarity with 7 languages
20. Single point of
update
Variable content/
conditional reuse
Automated
generation
Quick to update
and generate
Hosted in one
place
Code samples
Solution requirements
21. Challenges
Nobody said it was easy
Buy in and adoption
Needs to be easy to use and more convenient for
technical writers.
Responsibility & ownership
Split between functionality code and what can be
defined by technical writers.
Testing
So many different languages and environments.
25. Some interesting
findings
• Samples inconsistent per language
• Samples inconsistent per integration
• Changes introduced inconsistently
• Lack of awareness due to volume
• Scope for consolidation and automation
32. Results
Improved samples, easier process.
Consolidated samples
Consistency across languages and integrations.
Single point of updates
Make changes to CSV and autogenerate samples
All reused from one location
140+ becomes 35, reused with variable content.
33. “I'm loving this automated code
block feature!”
- Andrea S. (Technical Writer)
37. More to come…
Here’s where we’re going.
Automated testing
From manual rudimentary testing to including in
our devs testing frameworks.
More integrations
There are more integrations that use similar
samples.
Further simplification
Minimize redundancies as more libraries and
integrations are introduced. More dynamic.
40. Take action
• Don’t force your writers to be janitors
• Get buy in
• Look for repetitive “janitorial" tasks
• That impact documentation flow
• That impact quality
• Automate these tasks