Our JavaScript API documentation has an updated look and feel, with new content that can be updated by any Olarker. We've introduced a single page format with visual guides and useful examples. This means that you can decide, how, when and where to display the chat box on your site, as well as view and update visitor information.
Whether for your developer-friendly API, a self-help reference or a quickstart guide for new customers, here are some key behind-the-scenes takeaways from updating our documentation.
Good documentation is good writing
Searching online and offline for inspiration, I found many instances of documentation that was rife with formulaic detail, but unintelligible for the first-time reader. If it's not easy to read, then it's just a reference book.
Similarly, some documentation was hilarious but left me deeply unsatisfied. It was cheerful, sympathetic and self-deprecating ("How dry is this stuff?"), but wasn't a challenge. All the examples worked every time, with no unexpected consequences. The author was writing a smooth narrative that didn't have roots in reality.
As an example of excellent documentation, Parse.com's have very technical detail written in a very human way. Consider this gobbet about their password reset API function:
Resetting Passwords
It's a fact that as soon as you introduce passwords into a system, users will forget them. In such cases, our library provides a way to let them securely reset their password.
This isn't just a witty aside, it's a reminder of why a password reset is there in the first place. In our documentation, we remind people of occasions when the API might be overkill, when a simple setting on the website would be easier. In some places though, we'll give examples of why you would want to use one particular API call over others.
Out in the real world, I was reminded of CGP Books, guides that we were encouraged to use as 16 year olds studying for school exams in the UK. It's well over a decade since I last used one, but I've yet to see a better study guide.
They were packed with information. The designer tossed caution to the wind when it came to whitespace, but it's interesting to note how page design back then looks a lot like basic HTML today - numbered lists, underlined content, headings, bright colours and callout sections.
In the UK, the Government Digital Service has done an incredible job creating an engaging website. If you google for the next bank holiday (UK national holidays throughout the year), here's the page you're presented with:
If there's a better example of unambiguous writing on a governmental website, I've yet to see it.
Good documentation helps you get in, get out
More often than not, documentation is intended to help you quickly dive in, learn (or remind yourself of) something and get back out again to test or play on your own. With that in mind, the documentation was built for speed and simplicity.
Show, don't tell
Tutorial videos can have inline links, clickable chapters, good production value and branding. There's a time and a place for this, even on our own site, but for the API documentation we were acutely aware of a developer's desire to scroll and scan. LICEcap makes it incredibly easy to make GIFs in seconds.
As much as use explainer videos can be, a big problem with making embedded video content is how incredibly quickly it can become out of date. As we add, change or deprecate features, videos showing out-dated content is not useful as a reference.
A video works just fine when you're walking someone through something, but if you just wish to show something, an animated GIF works formidably. It also means that anyone on the team can quickly contribute content. While there can be a step-down in quality compared to video, the benefit of speed proved much more useful in this case.
If you do like video, but worry about production value, watch Chris Coyier's CSS Tricks videos. Watching him make mistake after mistake, while he learns along with the viewer, is content Bob Ross would be proud of.
Build for skim-reading
Previously, our documentation was laid out over several pages. The problem with this was that if you didn't know which API call you were looking for, it required clicking around blindly until you found the information you required. Why, for example, should a customer assume that messageCountForThisVisit was hidden behind api.visitor.get Details?
By including all of the API calls on one page we can aid discovery and reduce friction. We often found, for example, that customers could not find API calls and so created a support ticket, when the documented answer was there all along.
Build for speed
Our API documentation was part of our larger Rails app complete with controllers, redirects and regex pattern matching. If that made no sense to you, imagine how it was for Olarkers outside the engineering team to fix a typo.
It was tough to edit, worrying to deploy and could be affected by downtime to the main application. Edits involved loading up Vagrant, SSHing into a virtual machine and running a test version of our website. This was unnecessary in order to show visitors basic HTML text and images.
Similarly for our visitors, making a static page meant that there was no need to make a connection to our Rails app just to display relatively simple content. The consequence is that the page loads quicker, can be cached and helps optimize too.
What was your inspiration for updating your documentation? Let us know if you've had experience creating or editing API docs.
