How To Write Awesome Documentation

Michael Verdi

Hellooo!

Michael Verdi

SUMO Content Manager
michaelverdi in #sumo and twitter
Very Googleable
Slides: sumo.graymattergravy.com/slides/betterfm

I'm the new content manager for SUMO. I'm also new to Mozilla (though I've been using Firefox since v1 of course) but not new to open source or web communities. I often feel like I've lived many lives - I've been a mechanic on a nuclear sub, a high school teacher and a member of a theater company. I'm an artist and I love to tell stories. A little more than 6 years ago I was writing a script for a performance I was doing about virtual worlds, immortality and Start Trek. Like all of my previous performances this one included video. I wanted it to be live video from a virtual world but the time for that wasn't ripe. Anyway, I got very interested in both the technology and the techniques of telling stories with video on the Internet. I quickly hooked up with a tiny community (like a few dozen people) exploring the same thing. I jumped right in and became any early leader - creating a very popular tutorial site (that doesn't exist anymore) that we translated into 6 languages. Later my partner in crime Ryan and I also wrote a book based on the site along with helping to organize a conference and raise money to help fund cool projects and software tools.

What are we trying to accomplish at SUMO

Kathy Sierra by Rerun van Pelt

SUMO is already a pretty great manual. But we want to make it an even better one because every time someone gets helped by an article, they don't have to get help in the Forum or Live Chat.

So what are we trying to accomplish? SUMO is already a pretty great manual. But we want to make it an even better one because every time someone gets helped by an article, they don't have to get help in the Forum or Live Chat. And that's a win because an article can help thousands of people a day - it scales. Just like the number of Firefox users (40 Million?? since I started 3 months ago) scales. Plus knowledge base articles can be localized! Not so for our Forums and Live Chat.

We're not just trying to treat a symptom and send on your way. If possible we'd like to help keep you healthy or, in our case, teach you a little about your web browser. If we can do that, we might be able to take care of a future issue before it arises. That's potentially a second win.

So over the last three months I've done a bunch of research, user testing trying to see what kinds of things we can do to improve our documentation.

Techniques: Conversational writing style

How to set the home page (before)

Firefox shows the home page when you start it. You can change the home page to any web site, several web sites, or even a blank page.

How to set the home page (after)

Setting your home page in Firefox is easy. Can't decide on just one page? No problem. Firefox lets you set a group of websites as your home page. This article will give you some examples and step-by-step instructions for customizing your home page settings to best fit how you work.

This is a big thing we've been working on over the last quarter. One our goals was to increase the helpfulness of articles by 2%. So I rewrote our 5 most popular articles (how to set the home page being #1) using a conversational style and few other techniques that I'll get to in a moment, and we tested them. The results showed more than a 7% increase in helpfulness overall (measured by uses' responses to the poll at the end of each article).

Techniques: Emotion!

Humor is great if you can make it work. In our case, it's a little difficult because we translate everything into dozens and dozens of languages. In one draft of this article I had a nice pun. David - the native Swedish speaker - pointed out that by definition, English puns don't work in other languages. But there are other emotions you can touch. "I didn't know that!" or "I Rule!" are a couple. When you can take something complex and break it down into simple chunks or show someone how they can use something they've just learned to make their life easier, you can give them the experience of kicking ass. People don't care so much that you can set 52 pages as your home page in Firefox. What people care about is that you can open your email, news and Facebook by clicking one button.

Techniques: Images & Video

People have all different kinds of learning styles but in all the years of teaching I've done almost everyone prefers it when you can show them what you're talking about. You can make images or video even more effective by including words directly. For SUMO in particular, because it needs to be localized, it doesn't work for us to put words in the images but the next best thing is to outline what the words in the instructions are referring to. One feature we have outlined for a future version of the knowledge base is the ability to add words and call-outs to images like you can on Flickr. Doing it this way will allow us to localize them.

Techniques: Assignments, Challenges, Questions

Another natural part of conversations is a little back and forth. You don't usually just talk at people, you ask questions, they respond - it's a dialog and that's something that keeps your brain working. Also, just because you gave someone step by step instructions doesn't mean they actually did them. If they're like me, they'd of just read over them at least once to make sure you we're going to tell them to do anything stupid or too difficult. This is an opportunity to give them a little challenge. Reading about how to do something is different than actually doing it.

But people don't read webpages!

They scan them for keywords. They look for the pieces that are important to them (and if they don't see them right away they hit the back button).

That's all true but it doesn't mean we can't make the little bits that they do read enjoyable and effective. With practice you can do a lot with just a single sentence. The weekend before my first day at Mozilla I got my LDAP account, logged in and started by reading the new hire page on the wiki. There under the Don't Panic section was written, "People here are busy, but they're also really friendly, and they have all gone through it before. Ask. Learn. We already like you, don't worry." That last little sentence did it for me. It made me laugh and I called my friend to read the paragraph back to her. The reason I was so excited was because it let me know that I was in the right place.

7/7/10