Edit the Balsamiq Docs!

We've made it easy for anyone with a Github account to submit edits to our documentation.

As we've written about before, improving our documentation has been a focus of ours for a while. We've gone from one or two developers writing docs when they found the time to a team of about five people that make sure the docs are updated with each release.

We recently updated our docs site (sites, actually) to be easier for both readers and writers.

This year I attended the Write the Docs 2016 conference in Portland to learn from other writers. I also spoke on a panel discussion there to share what we learned through our documentation overhaul. And our documentation repositories are public so that anyone can use them as a starting template.

Looking at open source software projects we use and talking with other "documentarians" whose docs are on Github, I noticed that many projects invite documentation collaboration from readers via Github "pull requests". Since our docs are on Github, we decided to do it too.

We aren't an open source software project and we don't rely on volunteers for our work, but we often get emails about our documentation; Typos, text that's not clear, or out-of-date information, for example. Now, with a Github account, you can propose those changes directly in our documentation!

Here's how.

At the bottom of each article on docs.balsamiq.com and support.balsamiq.com you'll see a link called "Edit this page".

Clicking that link will take you directly to the Markdown source for that specific page in our repository.

To propose a change, click the "edit" icon to "fork" the repository. (You have to be logged into Github to do this. If you don't already have a Github account, learn how to sign up here.)

You can then edit the file. Add a brief explanation of your changes and click the "Propose file change" button to submit it.

Once you do that we'll immediately get notified and, if we agree with the change, we'll merge it into our "master" branch and it'll be live.

Since we added this, we've already had one contributor, Song Li, who fixed a link in one of our Sales FAQs. Thanks, Song Li!

And thanks in advance to our community documentarians who will use this feature. You're helping to make our documentation better for everyone.

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.

docs.balsamiq.comThe new Docs.balsamiq.com

Background

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.

  1. Moving our balsamiq.com site from WordPress to a static site
  2. I started using Markdown for blog posts and documentation (and then converting it to HTML for publishing)
  3. Increasing frustration with our existing knowledge base system, which made changes live as soon as they were saved and had a clunky editing experience
  4. 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.

Mike blogged about converting his personal site to Hugo

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.

An early layout. We eventually decided to combine the sub-section navigation and in-page navigation areas.

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.

The updated Support.balsamiq.com

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.

Reflection

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!

- Leon

Free Course on Rapid Wireframing with Balsamiq Mockups on Skillshare

We published a free course for Balsamiq users on Skillshare. The course, Rapid Wireframing: Finding the Right Product Design, is designed for those new to Balsamiq Mockups, but also features some demonstration of new features like Quick Draw and Alternates. If you're a veteran user, you may be interested in checking that out, and updating to the latest version to take advantage of these useful new ways of working on projects.

Here's a trailer to give you an idea of what to expect.


You'll learn how to successfully create wireframes for early stage product design as I show how to use Balsamiq Mockups to design interfaces with product teams, using the example requirements from UX Apprentice.

In the 51 minute course, you'll see how concept selection can be tackled with low-fidelity wireframes, learn to create rough sketches to explore ideas, and then transform them into interaction design solutions that can be refined quickly, and polished for presentation.

The class is perfect for product managers, developers, and those new to designing with wireframes. No prior knowledge or experience with interface design is required. By the end, you'll be able to present wireframes for a finished product idea and demonstrate a clickable prototype.

Start taking the free course at Skillshare now!