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 support team. She talked about the launch of their new customer-facing support documentation.

The help pages were designed to be self-service. The old layout organized things as a list of questions. There wasn’t any sense of hierarchy or importance to things. The first question listed was, “What are the ‘Your global feeds’ on the Dashboard?” So why was that the first question? Well, because it’d been clicked on the most times. It’s the most popular question because it’s the most popular question. Ultimately these question lists just didn’t make sense.

Mig Reyes and Ann worked on a new help site that, in short, would be browsable, intuitive, and reflect the actions and activity of users. It also needed to serve as a starting point for people to get up to speed with Basecamp. From the support team perspective they needed a landing page for resources, a flexible tool that provided for multiple ways of using a feature, and they needed a software platform that allowed for all of this to work well.

The new site combined a new CMS along with new help guides targeted toward specific use cases. It’s a cool combination of standalone guides with answers to common questions.

In writing the new docs the support team sought to be more concise in their writing. They also aimed for each doc to tell you specifically what you could do with the feature. Each answer in their FAQ section answers the question briefly while also providing a deep link in to documentation.

To edit content on the support site the team had to create a local development environment. They installed Xcode, Homebrew, git, generate an SSH key for Github, install Ruby, rebenv, bundler, pow, Jekyll, pull the repo from Github, and then bundle install and rake setup. It was that “simple.” They use this setup to stage changes to docs as well. By using git’s branches ability they can prep content before a release. Those same branches also allow for experimentation with the documentation.

In the first 2 months their support site saw 2,000 hits a day and support tickets were down 5% from with the previous system.