Lost your License key?
Retrieve Your License
Log In to Balsamiq Cloud
Our new Web App
Go to balsamiq.cloud
Log In to myBalsamiq
Our vintage Web App
Log In to myBalsamiq
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.
The new Docs.balsamiq.com
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.
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.
Before diving in, we made a list of requirements for our as-yet-undecided solution. They included:
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.
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
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!
We'll send you just one email a month and share a ton of information that you'll get before everyone else. More info about the newsletter here.
We'll never share your email address or spam you.
Your email is never published nor shared.
Pingback: Edit the Balsamiq Docs! – UX Blog – Balsamiq
Pingback: Scott Gallant on Adapting to Succeed – Balsamiq Champions – Balsamiq