Docs.balsamiq.com: Our New Static Documentation Site, Powered by Hugo
Last month we released a brand new web site for our documentation - docs.balsamiq.com. We also updated our support site with a new design and layout. This post describes what we did and why we did it.
Early last year we wrote about how we updated our support website for a better user experience. This included customizing our support center template to make it easier to browse and navigate, and putting more focus on tutorials and step-by-step guides. We also put in place some systems for writing documentation to streamline the process internally.
Since then a few events led us to want to improve our support and documentation site even more.
- Moving our balsamiq.com site from WordPress to a static site
- I started using Markdown for blog posts and documentation (and then converting it to HTML for publishing)
- Increasing frustration with our existing knowledge base system, which made changes live as soon as they were saved and had a clunky editing experience
- Search wasn't very good, making it hard for people to find what they were looking for.
Each of these factors alone probably wouldn't have led us to create a new support site, but combined they provided enough impetus to justify the work to move our content over to a new system.
Making a Plan
Before diving in, we made a list of requirements for our as-yet-undecided solution. They included:
- Versioning so that we can review history and work on updates before publishing them
- Ability to automatically generate a list of articles in a given category (for creating a table of contents)
- Customizable templates for different page types (article, TOC, main index, etc.)
- Support for Markdown
- Support for in-page anchors (automatically generated would be nice!)
- Next and previous buttons/links to articles within a category
A few of us researched options and we discussed the merits of each. Around that time a few other events led us converge on a plan.
- People on the internets started describing how static sites were being used successfully for documentation (not just websites). "How GitHub uses GitHub to document GitHub" was one of the most popular.
- I attended a meetup where Tom Johnson, a technical writer, gave a presentation on the benefits of using Jekyll (a static site engine) over traditional documentation techniques (you can see a recording of the same talk here).
- Mike converted his personal site to Hugo (another static site builder) and suddenly we had an in-house Hugo expert!
These three things gave us the confidence to start a project to convert our existing documentation to a static site built on Hugo.
Designing the Experience
We started a myBalsamiq project for the site and created some wireframes for the layout, navigation, and content.
Our primary design goals were to make it easy to navigate and to remove as much unnecessary stuff as possible.
After some discussion, we decided to separate our documentation articles from our support articles. This would allow us to have one dedicated site for our user guides, which are there to help our users learn the product. Our support site, on the other hand, is where people can go when they need help or have a specific question.
This also allowed us to make the transition faster, since only the documentation site would be built on Hugo.
These designs show our concept right before implementation.
Along the way, Mike took an opportunity to work on updating our existing support site design.
Implementation and Go-Live
Because several tasks had to be coordinated, Mike, Peldi, and I blocked off two days last month for the "launch-a-palooza" where we updated articles on the support site, switched to the new template, added the redirects, and a bunch of other behind-the-scenes stuff.
For the finishing touch, Peldi implemented a new search engine, Swiftype, across all our sites (not just our documentation and support sites). This was awesome, since it helped bridge the gap between our two separate help sites.
Finally, we decided to open source our documentation site code.
We are now working on converting our existing support site to Hugo, which, thanks to the work we've already done, shouldn't be too much work.
As the primary documentation writer, I was the person here who wanted this project the most and the one who has benefitted most from it. But I was also the most resistant, because it seemed like a lot of work, and I was concerned about all the old links, worried that many customers would be seeing our Sad Robot instead of getting the help they needed.
But Peldi and Mike's experience with large web projects made it happen and they knew how to handle all the details and loose ends to make sure the transition was by-and-large incredibly smooth. On top of that, Mike's excellent design work and Peldi's implementation of our new search capabilities made the end product better than I could have imagined.
I'm not sure what the rest of our company learned from this, but I learned that having the right team on a project can produce great results. I don't think I'll be so intimidated the next time I'm faced with an idea for a large project.
I think it's also important to note that, while much of the work on this project involved using new technologies, we did a lot of work up front to define the problem and write down what we expected from our solution. This project wasn't just a show of our technical capabilities, but our effort to improve our products and processes by making documentation easier for our writers and better for our customers.
Thoughts? Feedback? Feel free to share in the comments!