This week we launched version 2.0 of the relayr Documentation Center. The site was in desperate need of an overhaul: the design didn’t match our branding guidelines, the content was purely referential and not interactive, and worst of all, the information was outdated and poorly organized. It got to that point because we treated documentation as an afterthought, as something we could fix once we’d pushed the code out the door. This kind of thinking will set you up for failure.
Over the past several months, we came together as an organization to make documentation a priority and treat it as a product of its own. Good documentation is everyone’s responsibility, and once everyone adopted this attitude, we were able to deliver a comprehensive documentation repository. This post explains how we accomplished this and why your product won’t succeed without good documentation.
The key to successful documentation is context. In addition to explaining how the product works, your documentation has to serve the purpose of your product as a whole. This is especially true for a product that has a lot of moving parts, such as our IoT platform. Why is the user using your product? How do you explain the product so that it helps them achieve their goal? All of your documentation must center around this thesis. As an example, the relayr platform includes a variety of API endpoints, hardware and software development kits, several application protocols and a complex data routing engine. All of these technologies interact to connect physical devices to the Cloud, interact with them, and analyze their data. Thus, we based our documentation around this principle. If you don’t consider the bottom line of why someone’s using your product when documenting it, then your documentation will become haphazard and useless.
Here are some of the requirements we came up with during this process:
(Don’t forget to include a legend to go with your diagrams.)
We made the decision to organize the documentation based on a top-down approach starting at the Cloud component level. In order to understand the whole, each individual part must be documented — which is why we separated the documentation for the Cloud, Vertex and the IoT Starter Kits into their own sections. We decided to separate the API reference from the rest of the documentation so that it can be updated without any disruption to the main product documentation as our products evolve.
. └── content └── api | └── cloud | └── services | └── vertex └── cloud | └── getting-started | └── going-further | └── sdk └── iot-starter-kits | └── cisco | └── dsk └── vertex
Organizing our content in this manner also produced a logical URL structure. When publishing your documentation to the web, you must make everything as easy as possible to find. Sending your users through a maze of inconsistent site structures is guaranteed to drive them away from your product. How often have you abandoned a promising library or framework because it was too hard to figure out and nobody bothered to document it properly?
The new relayr Documentation Center is built on Hugo, a static site generator.
We decided to use a static site generator because it makes it easier to integrate information produced by our development teams. Page content on static sites is written in Markdown, an easy-to-read markup language, and converted into HTML. If anyone wants to contribute to the documentation, all we have to at relayr do is point them to a guide on Markdown syntax instead of training them on a fancy CMS or documentation software. The content is the most important part of the site — as far as the backend goes, if it can serve up the pages then that should be enough.
We chose Hugo in particular because it is built on Golang: a modern, high-performance programming language with a large and active community. Golang is best suited for backend systems, which allows us to focus strictly on the contents of our site. While the idea behind Hugo is to provide a good-looking site out of the box with minimal frontend tweaking, it includes many powerful template functions based on Golang’s robust template framework so that you can customize your site.
In this approach to documentation, customization is absolutely necessary. If you want to have an enterprise-grade documentation website, then simply slapping a premade theme onto your Markdown and calling it a day isn’t going to cut it. Get your hands dirty with whatever language or framework your site is running on and push yourself to develop the functionality you need (or check out Hugo’s very active community, which has lots of good ideas and solutions to common problems).
Most people would rather be done with documentation once they’ve released their product. Yet by leaving your documentation behind as an afterthought and going ahead with subsequent releases, you are setting yourself up for problems with your userbase. Here are some of the most effective ways to maintain a documentation center:
Good documentation is crucial to the success of your product. If you adopt a careless attitude towards the docs, then this attitude will carry over into your user experience. Your users will be the ones who feel the pain if you can’t be bothered to document your product properly. You must treat documentation as its own product, not as an afterthought. Otherwise, you may end up in a situation where the contents of the docs are nowhere near the actual functionality of your product. Nothing frustrates a user more than inaccurate documentation!