Documentation - The Next Generation

Larry Garfield
Director of Developer Experience
21 Sep 2016 is a unique and powerful development tool. However, because it’s so unlike any other development platform it’s not always immediately obvious just what it can do. A great development platform deserves great documentation.

For that reason, we’re proud to release a major overhaul of our public documentation. We’ve completely redesigned the information architecture (IA) to make it easier to navigate and easier to scan. We’ve also collapsed the multiple separate “books” into a single hierarchy to make at-a-glance navigation easier.

The new IA was based in a part on an online card-sort exercise we ran with several of our users a few weeks back (thank you to those that participated!) and in part from analyzing our Google Analytics logs. Nearly all of our most trafficked pages are now accessible in a single click (where some were 4 layers deep previously!), and several nearly-unused pages have been removed.

We’ve also added a new introduction section to provide a “big picture” view of how works: our general philosophy, the basic building blocks, and the build and deploy process.

The documentation itself is built with GitBook, a Node.js-based static documentation generator. It is, of course, hosted on itself. You can see exactly how it’s setup in the public GitHub repository. Oh, you didn’t know that you can host projects on GitHub with transparent integration and an automatic environment created for every pull request? See the docs for how.

In fact, we’d encourage you to have a look at the repository even if you’re not curious. This overhaul isn’t the last we’ll be working on the docs. Good documentation is an ongoing process, and we welcome your feedback. In fact, we welcome your Pull Requests, too. Have a look at our contributing guidelines and if you find errors, oversights, or simply something that isn’t clear let us know either with a Pull Request or simply file an issue.

Happy deploying!