Support: the wild west of documentation

Earlier this year, I was listening in on the Twitter stream for #writethedocs—a conference for technical writers—when one of the  speakers mentioned turning documentation from passive to dynamic.

 

Support: the wild west of documentation. — @gkoberger Fantastic #writethedocs talk. https://t.co/ZQc11NH3ad

— Aprill Allen (@knowledgebird) May 19, 2015

Gregory Koberger is a developer and founder of ReadMe, a documentation tool for developers. It’s intended to fill the need that developer communities have for up-to-date API documentation, but I could see a fit for DevOps in the enterprise, so I went digging some more, by way of hitting up Gregory with some questions.

 

Developers are notorious for hating on documentation. Can you explain why that is?

The biggest reason is probably that it feels like busy-work. If you think they hate writing documentation, though… it doesn’t compare to how much they hate how bad other people’s documentation is.

Programmer’s live in a very logical world. An out of place colon can bring a whole program crashing down. The API is written in a logical programming language, and it’s consumed by a logical programming language. Yet we’re forced to serialize knowledge about it in English, which is incredibly ambiguous. Lots of logic and meaning is lost or mutilated when transferring knowledge of how something works via written language.

What are the mistakes you see people making with documentation?

The biggest mistake is just dumping people into paragraphs of text, with no warning. We know so much about the user and about the API or code library, we should be able to remove everything that’s not relevant to the user. New users should get a nice high-level onboarding flow, while more experienced users probably want information on error messages or reference guides.

Taking the time to read through your documentation as though you’re a user is another big thing people don’t do. Do your best to forget all knowledge you have. Does your documentation have working examples? Does it mention if the API key should be passed as a header or a query string? Do you mention any weird edge cases? Make sure you don’t leave out details that are obvious to you but wouldn’t be to other people.

What makes documentation great, and do you have any examples to point to?

How does ReadMe work to solve those well-known roadblocks to documentation?

One of the biggest things we do is let people deploy documentation from semantic metadata. That sounds more complicated than it is – basically, it just means that we let people sync Swagger (and other similar specs) from GitHub. This let’s us divide up the work. Humans can still write paragraphs of text, but ReadMe can do things like generating code samples and letting users test out the API inline.

Of course, we’re just getting started! Our goal is to “redefine” how people look at documentation. Look at Slack, for example – it’s a “chat app”, but it’s quickly becoming a full-fledged platform that brings everything together into one cohesive workflow. That’s what we want to do with documentation. Documentation is the center of the API ecosystem; it’s the glue that brings it all together.

What kind of outcomes can a business expect when they put time and effort into well-maintained API documentation?

Look at Stripe vs Braintree. Similar products, similar pricing, similar everything. Stripe won out, because they had a huge focus on documentation.

Your API is your best bizdev hire, and documentation is the entire user experience. Partnerships aren’t made by people in suits anymore; they’re made by developers who share information and functionality via APIs.

How do you see the way we approach documentation evolving?

I’m biased, but I think we’re going to see documentation becoming much more interactive. Look at, say, O’Reilly books. They’re static, and everyone gets the same book. We’ve really just digitalized the way documentation was done in an analog medium. Most documentation is written using Jekyll or Sphinx, and is deployed statically. We know so much about both the user and the API! We should be able to give everyone a custom-tailored experience that takes into account their skill level, programming language, time using the site, activity on the site, and more.

While we definitely love APIs, there’s a ton of great uses of ReadMe. A good portion of our users use it for internal documentation. (StatusPage just wrote about how they use ReadMe, here.) Another big use-case is open source code libraries.

I’m incredibly excited about the future. Making the documentation the central hub for your developer experience is our main goal. That means we want everything from support to dashboards to API statuses to have a home in ReadMe. We’re looking to become a true “developer hub”, that sits right in the middle of your entire ecosystem in a simple, beautiful way.

Gregory Koberger is a designer and developer living in San Francisco. He founded ReadMe, which makes it simple to create beautiful documentation.