After attending Write the Docs 2018 (Portland, edition) and watching a YouTube video, I’ve got it figured out: How you (i.e. anyone) can create documentation as cool as Twilio’s–a consistent entry in lists of the best API documentation examples.
All you need to do is follow these six steps:
- Think, plan, and work iteratively.
- Infuse user research and analytics into your entire writing process.
- Treat your documentation as a product.
- Do what’s best for your documentation customer.
- Create and support a writing process that enables contributions from outside of the writing team.
- Build the CMS that supports all of the above.
You’ll need to understand that it took them a few years to get to where they are, today. And, it sounds like they’ll keep moving the bar.
But, don’t be discouraged. The sooner you start, the sooner those three to five years will be behind you.
A little background
Twilio’s Kat King opened Write the Docs 2018 in Portland this May, starting the conference off with a strong sense of user testing and research. That always gets my attention at a tech-writing conference. The next session by Jen Lambourne continued by describing how she applied user research on documentation. I’ve been going to tech writing conferences for quite a while and I can’t recall going to one with such a user-research focus.
I’ll make references to these videos, in what follows in case you want to go straight to the source (something I always encourage). The practices they describe, however, are straight out of user-centered-design. You can also see some of my favorite books on the topic for more background.
What’s noteworthy here is that the Twilio team has applied them successfully to their documentation–proving, if nothing else, that documentation works like any other product (and perhaps works best when treated as one).
So, here’s how the steps work: