A few weeks ago, we rolled out a brand new documentation site. This post goes into more detail about the technical aspects of how we keep the Hologram docs informative and up-to-date.

Source

We write our documentation in Markdown and keep the source in a Git repository. We previously used pages in Wordpress, but it became difficult to collaborate and review changes, especially when a new feature required making changes across many pages. A version control system like Git solves many of these problems, and it also allows our users to contribute to the docs. We've published the source repository on GitHub, and every page of the documentation now has a link to suggest edits:

Edit button below the table-of-contents sidebar[/caption]This link goes to GitHub's in-browser editor for the corresponding source file, which allows anyone with a (free) GitHub account to submit a pull request. The GitHub editor is a great feature for user-contributed changes since it doesn't require locally cloning the repository, or even knowing what a pull request is.

Building

We use a Node.js-based static site generator called Metalsmith to turn the Markdown source into HTML files. Metalsmith relies on a plugin system to do most of the actual compilation, and we were able to use a handful of existing plugins to get most of the functionality we needed. These included:

• metalsmith-markdown for Markdown-to-HTML conversion
• metalsmith-prism for code syntax highlighting
• metalsmith-autotoc for generating tables of contents based on headers in a page
• metalsmith-layouts and metalsmith-in-place for templating page layouts and partials with Handlebars

We also wrote a few plugins and Handlebars helpers for some of the more specialized pages and UI elements, like the reference index. The biggest stumbling block with Metalsmith was generating navigation links on index pages and sidebars. This was mainly a problem because we had different docs page types (guide, reference, tutorial)--each with a slightly different directory/URL structure. This meant we had to implement a few different tree traversal helpers to transform the output of the metalsmith-navigation plugin. Overall, Metalsmith was easy to work with and flexible enough for our use case. I would consider using it for future static site projects.

Integration

The main hologram.io site still runs on Wordpress, so we needed a way to serve our compiled docs while maintaining a consistent look and feel across the whole site. One common approach is to serve static content on a subdomain, and to re-create the same layout and styling so that the static pages match the main site. It's even possible to configure your web server to serve these pages from a directory URL (example.com/docs) instead of a subdomain (docs.example.com).We took a slightly different approach: the compiled HTML pages are actually page fragments, and our WordPress install is configured to stitch these fragments into the main page template when someone requests a page in the /docs directory. This means the header, footer, and styling on the docs pages is guaranteed to be the same as the rest of the site, since they're all being put together by Wordpress. Another benefit is that the docs can be more easily customized for logged-in users. For example, code snippets could include a user's API key so that they can directly copy and paste a working example. There are tradeoffs with this approach, mainly that it's more difficult to create a standalone documentation build without the whole Wordpress site. But for our purposes it's been working well.While the most important part of product documentation is, of course, the content itself, it's become evident that our investment in the right tools has helped improve the user experience already. And just as importantly, these tools will continue to support our documentation needs into the future.

Ready to manage your fleet with our IoT stack? Check our cellular platform plans.