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.

Get the Inside Scoop

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.

Leave a Comment

Your email is never published nor shared.