Toggle navigation

Behind the Scenes of Our Documentation Process

We are always committed to improving our support website experience. Read this blog post for the most recent changes to the Documentation site.

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.

Recording a need

Documentation updates can be prompted by several actions. Here are the primary triggers:

  1. A customer contacts us (via phone, email or our forums) and mentions a typo or mistake in our documentation or has a problem that should be explained better on our support site
  2. We add or change something in our product and therefore need to update our documentation
  3. A support employee mentions that lots of people keep asking the same question and asks to create a dedicated FAQ or article about it

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:

  • Desk - for email support and for managing our documentation knowledge base
  • HipChat - for communication among the team, and
  • Pivotal Tracker - for tracking issues and documentation requests.

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.

Some conversation in our HipChat Docs room, including status updates from Pivotal

To stay in the loop I also monitor the Support HipChat room so I that can see what people are having trouble with.

Some conversation in our HipChat Support room

Inside Pivotal

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:

  1. The Action label group, describing what kind of task was needed
    • "New" means this is a new article that should be created
    • "Update" means that this is an existing article that needs updating (e.g., out-of-date screenshot, missing feature/function)
    • "Clarify" means that something in this article is not clear and should be reworded or modified for clarity
  2. The Actor label group, describing the type of documentation affected
    • "FAQ" is for any FAQ (product, licensing, installation)
    • "Documentation" is for product user guides (anything in the Mockups for Desktop or myBalsamiq "Documentation" category or any of the plugin User or Admin guides)
    • "Tutorial" is for tutorials
  3. The Category label group, describing the affected product or category within the Actor group (myB, Desktop, GDrive, Licensing, etc.) - this is optional

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!).

A few stories in the Pivotal Docs project


To help with planning, I devised a system for estimating the work required for our documentation and tutorials stories. Here's the current version:

  • 0 points - No change needed (e.g., duplicate or no longer applicable)
  • 1 point - Typo or minor wording change
  • 2 points - Updating or adding a screen shot, adding a new section to a document or a major re-write of one or more sections of a document
  • 3 points - Creation of a new article or video

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.

New additions

A new writing tool

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.

Our ScreenSteps HTML template, stripped down to meet our needs (click to see more of it)

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.

A Style Guide for docs

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.

A work in progress...

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!

Leon for the Balsamiq Team

Leave a Comment

Comments (3)

  1. Pingback: Our New Static Documentation Site, Powered by Hugo – UX Blog – Balsamiq

  2. 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.