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
We recently wrote about some of the changes we made to our support site in the last year. Following up on it, this post goes into depth about the details of our process for adding content to our support site.
As we are a software company, our process for adding documentation is not unlike our process for adding features and fixing bugs. Here's how we do it.
Documentation updates can be prompted by several actions. Here are the primary triggers:
As much as possible we try to track things our customers want to know more about and things they're frustrated by. Our process hinges on frequent communication between our customer-facing staff and our documentation and product people. We also want to make it easy to then record those frustrations as tasks and assign them to the right people. I am responsible for our non-sales related documentation.
The three main tools we use in our documentation workflow are:
If an issue related to documentation is raised in Desk (our direct customer support channel), it can be assigned to me. We also have a dedicated HipChat room called Docs, where we discuss ideas for new support articles and give feedback on existing ones.
To stay in the loop I also monitor the Support HipChat room so I that can see what people are having trouble with.
We use Pivotal Tracker for our product feature requests and bug fixes, so it made sense to use it to track documentation tasks as well. For a long time our documentation issues were filed in a general "Website" project, which was a catch-all for anything affecting our website (documentation, page redesigns, CSS alignment issues, etc.). But we recently created a separate project called "Docs" just for documentation and tutorials and moved our documentation stories into it.
We also made it easier to add issues to Pivotal by connecting Pivotal to HipChat via Zapier. Now, when a documentation story is created or updated in Pivotal, it is shown in HipChat (you can see this in the first HipChat screenshot above). Conversely, we can create Pivotal documentation issues directly from HipChat by typing: "Pivotal(issue name)". Employees can also create Pivotal stories directly in our Pivotal Docs project.
Once the documentation tasks are in Pivotal, I can organize them and begin work on them. Organization within Pivotal can be a bit of a challenge though, so I came up with a few additional processes for getting a handle on our documentation stories.
After we separated our documentation stories from our other website stories I quickly reviewed each of them. I started by labeling those I didn't understand as "to review." Those that appeared to be no longer relevant I labeled "to remove." The people who created those stories pitched in and added their comments or deleted them and we reduced the size of the backlog a bit.
Next, I tried to think about how to prioritize and group the remaining stories because I didn't have a good way to get a sense of urgency and difficulty. One of the first things I did (perhaps because diving right in was too intimidating) was develop a labeling system.
After some iteration, I came up with three categories of labels:
When adding the tags I try to place the tags in this order: "Action (Category) Actor" so that they make sense when written out. E.g., "New Installation FAQ", "Update myB Documentation", "Update Tutorial".
This has worked pretty well, as the labels seem to fit most requests and I'm able to add them easily when a new Pivotal issue is created. It also helps me tackle these issues in bulk more easily. So, for example, one month I made a point of addressing all "Update" stories in order to try to get our documentation up to date with the latest release (I didn't make it all the way through, but I made a big dent!).
To help with planning, I devised a system for estimating the work required for our documentation and tutorials stories. Here's the current version:
There is a big jump between 2 and 3 points (writing a long article or creating a video can take a couple of days), so it's not exactly a linear scale, but it's simple and clear enough to be useful.
One of the frustrating things for me when I started writing new documentation was just how long it took. For a simple document it often took a full day. One of the reasons is that our documentation is written in HTML (which is ok, although it adds some time) in a web-based tool (which makes iterations and drafts a bit challenging) and often requires screenshots (which can be a pain to create and upload).
What I really craved was one tool for everything, preferably that could work offline. After a lot of research, I settled on ScreenSteps Desktop, a tool for writing help guides that has built-in image capture. This was the killer feature for me. It can also automatically resize images to a set width to fit our web template. This saves me from having to edit them after I've captured them. And it outputs HTML with the ability to customize the output template with variables so that it generates the exact HTML that I needed to paste into Desk. My edits to the default template included removing the header and footer, mapping to the correct images directory, and adding specific CSS class names that we use on our site.
I haven't used it for our main documentation yet, but it worked great for our "How-To" guides, which are heavy on images.
The process of publishing images also got easier when we moved to using GitHub to manage uploading our images, meaning that I could drag and drop them from my computer rather than using FTP.
Finally, we wrote a style guide for our documentation (although I haven't gone through the process of updating our old docs with it). It covers topics like rules for HTML and how text should be capitalized and formatted.
One of the big things I was hired to do was improve our documentation and I'm pleased with the new content and processes we've added in the the last year. The process is a lot smoother than when I started and I'm hopeful that our content will take another big leap forward in 2014.
Still, I know that as a UX designer turned Doc writer I have a lot of room to grow, so I'm focusing on improving my abilities. Although I've been struck by the many similarities between UX design work and writing documentation. For instance, the process of creating something based on a specific need, giving an orderly structure to it and then refining and polishing it seems to activate the same neurons as designing a UI for me.
It also has many of the same challenges as my UX roles. Much like coming into a company as a new designer, I inherited a "product" (our support site), which had existing content and an underlying technology platform, both of which were limiting in some way. There is a significant cost to shifts in either that can outweigh their advantages. (We have researched other documentation platforms but haven't found one that meets our needs much better than what we have, so I'd love to hear what works for others.)
Fortunately, I've had help throughout the year. I adopted the good practices that had been established when I arrived. And I started paying a lot more attention to other support websites and made an effort to understand how they were designed. I also attended the Write The Docs conference last year, where I connected with other doc writers and learned about the resources and tools that they use.
I'm still learning though, so I welcome your advice or feedback 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: Docs.balsamiq.com: Our New Static Documentation Site, Powered by Hugo – UX Blog – Balsamiq
Ooo. Thanks for drawing my attention to the Write The Docs conference! Did you go again in 2014? Will you be going this year?
The timing didn’t work out last year or this year. But I’m hoping to go again! They also have local meetups in some cities.