Write the Docs: Ann Goliak — Helping the help pages

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Ann works at 37signals on their sup­port team. She talked about the launch of their new customer-facing sup­port documentation.

The help pages were designed to be self-service. The old lay­out orga­nized things as a list of ques­tions. There wasn’t any sense of hier­ar­chy or impor­tance to things. The first ques­tion listed was, “What are the ‘Your global feeds’ on the Dashboard?” So why was that the first ques­tion? Well, because it’d been clicked on the most times. It’s the most pop­u­lar ques­tion because it’s the most pop­u­lar ques­tion. Ultimately these ques­tion lists just didn’t make sense.

Mig Reyes and Ann worked on a new help site that, in short, would be brows­able, intu­itive, and reflect the actions and activ­ity of users. It also needed to serve as a start­ing point for peo­ple to get up to speed with Basecamp. From the sup­port team per­spec­tive they needed a land­ing page for resources, a flex­i­ble tool that pro­vided for mul­ti­ple ways of using a fea­ture, and they needed a soft­ware plat­form that allowed for all of this to work well.

The new site com­bined a new CMS along with new help guides tar­geted toward spe­cific use cases. It’s a cool com­bi­na­tion of stand­alone guides with answers to com­mon questions.

In writ­ing the new docs the sup­port team sought to be more con­cise in their writ­ing. They also aimed for each doc to tell you specif­i­cally what you could do with the fea­ture. Each answer in their FAQ sec­tion answers the ques­tion briefly while also pro­vid­ing a deep link in to documentation.

To edit con­tent on the sup­port site the team had to cre­ate a local devel­op­ment envi­ron­ment. They installed Xcode, Homebrew, git, gen­er­ate an SSH key for Github, install Ruby, rebenv, bundler, pow, Jekyll, pull the repo from Github, and then bun­dle install and rake setup. It was that “sim­ple.” They use this setup to stage changes to docs as well. By using git’s branches abil­ity they can prep con­tent before a release. Those same branches also allow for exper­i­men­ta­tion with the documentation.

In the first 2 months their sup­port site saw 2,000 hits a day and sup­port tick­ets were down 5% from with the pre­vi­ous system.