Developer Blog hand with wrench

Good documentation: More than just a common courtesy

Brian Lemke

Jan 16, 2017
Full Metal Jacket Donut Scene - not commiting to things has consequences

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.

Context and requirements

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:

  • One-stop shopping. The Documentation Center needs to be the sole source of knowledge on all aspects of the relayr platform. Everything must be kept under one roof. Even though there are many good free tools available for generating various types of documentation (such as Swagger for APIs), scattering your documentation around multiple websites looks lazy and frustrates your users.
  • One consistent voice. No matter how many people you have writing documentation in your organization (ideally everyone), the end product must appear as though just one person wrote it, as opposed to a dozen. Give everyone a style guide, a list of typographic conventions, and a standardized structure and process so that the end result is consistent.
  • Hands-on tutorials. Don’t bother with a big, confusing wiki or reference page. Most users these days — particularly the technical ones — want to get their hands dirty and learn about your product by trying it out. Don’t let your users down by offering a couple of half-baked walls of text. It sends the message that they’re just supposed to figure it out on their own and that you don’t care if they get it or not.
  • Real examples. Even if your documentation is strictly a reference guide, you need to give your users real examples to show them how your product really works. Use actual values in sample API calls and in your sample data schemas. This helps you to create context for your documentation. If you’re just going to list functions and entities without any sort of context, then you may as well just tell your users to go look through your source code.
  • Strong visuals. While they may be a pain to maintain, screenshots of the UI provide a clear indication of what the user is supposed to see and where they have to go without having to stumble through a written explanation. You need to make the extra effort in order to save your users time and frustration.
relayr Architecture Diagram

(Don’t forget to include a legend to go with your diagrams.)

How we organized the content

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?

Building the site in Hugo

The new relayr Documentation Center is built on Hugo, a static site generator.

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).

Maintaining a good documentation site

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:

  • Treat documentation as a feature during development. Documentation is a crucial part of the development process and, ultimately, the final delivery of the product. It must be addressed during sprint planning/backlog grooming well before a release.
  • Add new features to the site. Good documentation means giving your users more than just words and screenshots. We’re planning on building an API test console to let people interact with our APIs using real examples and integrating it into the main site.
  • Set aside the time to do it. This may sound like a no-brainer, but it’s like flossing your teeth: if you put it off for too long, then you’re going to have big problems later on.
  • Give it to your new hires to try out. What better way to test your documentation than someone who has an interest in using it and understanding it (i.e., someone who just started at your organization)? If your newbies can’t make any sense of it, then how do you think your users will feel about it?

Conclusion

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!

relayr · Creative Commons Attribution License