An Evolution in Documentation

Originally published on the Clarify.io blog. View archived copy.

Last week, I talked about “Documentation as the Third User Interface” and walked through the three times people use your documentation:

• When they’re getting started;
• When they’re building something; and
• When they have a problem.

Doing one of those is easy, two is a challenge, and three is something else entirely. It requires not just great documentation but delivering it in correctly-sized and easily understood chunks.

At Clarify, we’ve pounded on our documentation from various angles, both in terms of content and in how we deliver it. This is our underlying thought process through each stage so far.

Version 1: The Developer Portal

The first version of our documentation lived within our Developer Portal in a mix of static files and dynamic content within our Django-based CMS. Since this was written by one of our founders – Ivo Rothschild – who also wrote significant pieces of the backend in Python, this made sense. The docs were close to the code and could be tracked like everything else.

The downside was that updating the docs often required updates in both Django and in the underlying templates. The Django updates could be performed by anyone but the template changes required a redeploy of the portal. This put the development team on the critical path for things as small as grammar tweaks.

Version 2: WordPress

The first conversion was moving everything from the Developer Portal to bring it under one umbrella in WordPress. The main website was already there, so it made sense. It was easy to get started, it gave us one place to manage all the content, and – more importantly – didn’t require redeploying anything to fix a comma. Not bad at all.

The downside was multi-layered:

• First, to accommodate the variety of page layouts, we needed a variety of WordPress page templates.
• Next, embedding Javascript, Github Gists, tab layouts for different languages, etc into the site required one plugin after another. While we didn’t notice a significant slowdown, this increased the likelihood of choosing a insecure plugin.
• Next was the lack of fine-grained version control or peer review. This was the biggest for me personally as I write much of the documentation and any mistakes immediately became 100% my fault.
• Finally, we didn’t have a good way to accept contributions from our community. We know we’re not going to discover every typo, clever hack, or useful optimization, so we want to encourage the community to feel free to speak up.

Overall, this was a step forward but not far enough.

Version 3: Github Pages – Where we are Now

Of course, before and throughout this conversion, we looked at what our contemporaries and colleagues were doing. Some had shining examples of what to do while others had great examples of what to avoid. One of the most important aspects to us is the ability for someone – really, anyone – to fix issues or add helpful information quickly and get it out there. In this regard, we looked towards SendGrid and their Github-based approach.

To cut to the chase, you can see our source code includes here.

Getting rolling was pretty simple:

• First, I followed the Github Pages documentation to create the repository and local Jekyll environments. Our docs repository is available here.
• Next, I individually downloaded the contents of our docs section, put them in the proper folders, and updated the urls. This created a mess of html, css, and Javascript with tons of duplication.
• Once the basics were working, I started refactoring. First, I stripped out the headers and footers, then the sidebar, and then started working on the templates. This was not fun as the site was initially built using a “design without writing code!” service which created CSS that made Cthulhu cry for mercy. I digress..
• Once the templates worked, I started the most important task: managing the code. This is where things got a little more challenging.

We needed two important things: a) a way to display all of the various language samples and b) a way to make sense of the individual samples.

To display the samples, we decided tabbing was the best option. To get the visual effect, we used the jQuery plugin Easy Responsive Tabs. It’s fast, simple, and – most importantly – we can link to individual language tabs. It means when someone asks a Ruby-specific question, we can send them to the Ruby samples directly. Most of the tabbing systems didn’t support that.

To make sense of the code itself, we needed a syntax highlighting tool. There are tons out there, but Nicolas Grenie (@picsoung) of 3Scale pointed me to highlight.js. It is hands down the best one that I’ve found. It handles over a hundred languages, has dozens of styles, and required almost no changes to the code. Wrap it in ‘pre’ and ‘code’ tags with a ‘class’ and you’re done. It doesn’t get much easier.

You can see our entire code sample library here. Yes, some refactoring is coming.

Version 4:  Looking Ahead

In the short term, we’re completing the Quickstarts in a number of target languages and simplifying the overall page layouts to remove the unnecessary bits. Stylistically, we want it to remain connected to the main site but have its own structure. Further we have a ton of new features, functionality, and use cases in mind that we’re planning to write up and share. We also want to find great ideas from the community that we’ll include as we can.

For the longer term, we’re already admiring packages like TripIt’s Slate. The improvement over Github Pages may be marginal but the automatically responsive nature and the smooth, location-aware scrolling – as seen in Dwolla’s documentation – is compelling. More than anything, we need to make sure we’re solving the developers’ problems, not just using a shiny new tool because it’s a shiny new tool.

So which is best?

Almost inevitably after talking with someone about our process, someone asks “which is best?” My long answer:

At the beginning, we were deploying constantly and making changes but the underlying functionality wasn’t changing a great deal. Therefore, having a long deployment cycle was okay.

As we got our feet under us and needed something more flexible, WordPress fit that role nicely. We got clean, SEO-friendly URLs with zero effort and we could restructure and add things quickly.

As things got more advanced and complex with functionality and more code samples, Github Pages has been a fantastic tool. We look forward to integrating and deploying more samples and clever solutions from the community.

As our platform grows and more features requires more documentation, I think the Slate system will make sense and give people the tools and information they need to get the job done.

So again, “which is best?”

We used the right system based on the concerns and requirements we knew and understood. 😉