Tutorialist Driven Documentation for developers

Have you ever heard this:

“I really enjoyed reading that API’s documentation — it was well organized, with detailed, well-explained examples in our language of choice.”

If so, I envy you. More often, this is the typical experience.

[Google a specific error]

[Top result: Stack Overflow. Some person has explained a quirk in the documentation, and provided a better explanation and example than the official documentation.]

There has to be a better way.

A lot of developer-oriented documentation is oriented towards an older style of programming, and I would argue, and older style of reading. As my model “old style” documentation, I present to you the wall of text that is the HAProxy configuration documentation. There is a “getting started” guide, but it’s meta information and background on load balancing . Then, there is the full configuration, which gets into extreme detail of each configuration option after more theory. Load balancing may be a complex application, but the lack of examples for the most common scenarios is something that makes me suspect that many persons visiting this reference guide visit third party resources. I call this the “abyss style” documentation, where if a developer only had this documentation to reference, they may very well need to spend an hour reading documentation before even starting to code. You could also call this an esoteric style of documentation, in that you must have already completed a task to understand it.

Developers in the UX world have long understood that the web as a medium does not lend itself towards print-based read-every-word text. This is very much ubiquitous outside of areas which are literally a replication of print-based media (ie. NYTimes Opinion section). BuzzFeed clickbait, Medium posts (how meta), and YouTube “Top 10” are all list-driven. They accommodate both styles of reading (or viewing) — a user may browse, or read in depth a particular point they are more interested in, without reading information they may find long winded. Documentation publishers — let’s learn what the media world already knows — users are not going to read 95% of what you write. Let’s make the 5% top notch to compensate.

Tutorialist driven documentation (the other TDD)

You download a new app. You don’t read the documentation, there is an on-screen tutorial that walks you through the most critical pieces that you need to know in order to function. At a certain point, you advance beyond the beginner stage and you become curious enough to explore the rest of the app. You can figure out the more complex parts on your own. Every 6 year old playing an iPhone game could tell you a variation of this. Then, why as developers and technical writers do we subject ourselves to some “holier-than-thou” practice when presenting developer-orientated documentation? In my view, developer-oriented documentation needs to have the target mindset of the end-consumer, even though we know that the target audience is heterogeneous; “developers like us”. Developer-oriented products (and therefore, documentation) gain faster market share when a larger proportion of developers can grok the concept in little time. Three interesting projects I’ve seen use this tutorialist style to teach a developer-oriented concept are:

ExpressWorks — Learn Express.js via terminal-style game and “assignments”

Vim Adventures — Learn vim by using the keyboard to navigate on-screen text

LeanYouNode — Part of the larger NodeSchool series. Similar to ExpressWorks.

It’s 3 AM. Do you know what your client’s developers are searching for?

I want you to Google [Name of company you work for] API. How useful was it? How quickly could a developer you don’t know, without industry experience start to utilize what you want them to utilize from the first result? If you’re cringing at an answer, there is a good chance that you should begin tutorialist driven development. Don’t be afraid to consult marketing to see what these external developers really want — look at inbound search keywords, social media inquiries, get customer feedback at meetups. Maybe you are at a stage where there is broad interest, but search results don’t reflect what you want. Or, perhaps there is a developer community, but outdated docs or Stack Overflow results have higher rankings than your own documentation. Third party developer experience is so important because a good integration or demo will entice even more developers to want to work on your platform, in turn driving more platform growth.

Don’t be that project. Write good developer-oriented documentation.

Bonus: “I REALLY need my users to read the docs from front to back. They may get themselves into a bad state and hate my product.” In the beginning, put the user into a “training wheels” mode, such that they can’t possibly do this (ie. using pre-canned queries, configurations). Lots of developers are naturally power users, and will find out how to break your system the fastest way possible in ways that you could have never anticipated. Don’t call it “training wheels” though — developers like tutorials, but they don’t like to think they need it.

Like what you read? Give Aaron Corso a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.