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.

1. Let writers write
Automating the boring stuff for
our docs team

2. Who are you?
What is Adyen?

3. Patrick Hammond
Technical Writer
Coder
Project Manager
Dog owner

4. Adyen
Founded 2006 in Amsterdam
Payment Service Provider
Help companies to accept payments
Across all sales channels

5. The past…

6. Write the Docs 2017

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.

8. The present…

9. Adrienne Andrea Anusmita Chris Johan
Karl Matt Miguel Patrick Paula
Ruby Sam Scarlet TijnRuslan

10. One voiceDifferent audiences1000 reuse items2000+ pages
Adyen Documentation
So much content…

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.

12. DocOps
DocOps involves facilitating a content flow that is:
- Collaborative
- Agile
- Continuous
- Enables reuse

13. DocOps
Our little group within a group
JanPatrick Tijn

14. DocOps
The tools we use every day to make the tools we use every day
GitPython Jenkins

15. Publishing flow Linter Code sample generation
DocOps tools
Some of our work so far…
Content integrity checks Broken link checks Code sample testing

16. A problem to be solved:
code samples

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.

22. Biggest challenge:
so much data
Attempting to climb a mountain of code.

23. How did we do it?

24. Stage 1: Analysis
Analyze current code samples to determine
patterns and variations.

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

26. 2. Agreement
Gain agreement on how you want samples to
look at the end.

27. 3. Breakdown
Find the patterns, then divide and conquer.

28. 4. Rebuild
Develop the logic to rebuild these chunks into
code samples per language.

29. 5. Launch fast, iterate
Applying the Adyen Formula to our work.

30. Generator flow
Body text here

31. Technical writer flow

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)

34. “The generation went beautifully!”
- Paula H. (Technical Writer)

35. “Oh, hey, this is actually pretty
cool…”
- Almost every developer

36. The future…

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.

38. Demo

39. Ok, that’s all good.
What can I do?

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

41. Thanks for listening!

42. Q&A