{"id":1196,"date":"2010-07-23T11:52:22","date_gmt":"2010-07-23T18:52:22","guid":{"rendered":"http:\/\/blog.mozilla.org\/sumo\/?p=1196"},"modified":"2010-08-26T09:38:50","modified_gmt":"2010-08-26T16:38:50","slug":"writing-awesome-documentation","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/sumo\/2010\/07\/23\/writing-awesome-documentation\/","title":{"rendered":"Writing Awesome Documentation"},"content":{"rendered":"

\"Mozilla-Summit-Day2-20100707-IMG_3682.jpg\"<\/a>
\nImage by Roland Tanglao<\/a><\/em><\/p>\n

For those of you who didn\u2019t go to the Mozilla Summit (which was amazing BTW<\/a>) or didn\u2019t see my presentation, I wanted to recap it for you because it\u2019s the basis for some of the things I\u2019d like to do with the Knowledge Base moving forward.<\/p>\n

Last quarter, we worked on finding ways to increase the helpfulness of our articles by 2%<\/a>. We started to run some multivariate tests but found that they\u2019d take too long to give us results that we could use. So about 2 weeks before the end of the quarter, we decided to try rewriting some of our most popular articles. Instead of running this test through the metrics team\u2019s tools (and only sending a fraction of the SUMO traffic to each article) we just made the new articles live for everyone. This allowed us to get enough results from the survey at the bottom of each article to get some meaningful results.<\/p>\n

What we found was that the rewrite increased the helpfulness of these articles by over 8% translating into helping about 800,000 more people each year.<\/strong> This is really important for us because helping more people with knowledge base articles is the only way we can keep up with our 400 million (and growing) users in dozens of languages.<\/p>\n

So here are some examples of the techniques I used in the rewrite of the How to set the home page article<\/a>. You can see the slides from the presentation here<\/a>. The main idea I focused on was to use techniques that keep your brain engaged. These mostly involve trying to keep things sounding like an actual human conversation which is more difficult than you might think.<\/p>\n

Conversational writing style<\/strong>
\nBefore:<\/p>\n

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.<\/p><\/blockquote>\n

That\u2019s accurate information.<\/p>\n

After:<\/p>\n

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.<\/p><\/blockquote>\n

This version sounds a little more friendly. It also doesn\u2019t try to list everything the article explains but instead gives you an overview of the types of information included. This way a reader can quickly say, \u201cYes, I want examples and step-by-step instructions.\u201d<\/p>\n

Humor, emotion! and motivation<\/strong>
\nUsing 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. I cut many of the funny lines I tried to write because they would be difficult or impossible to make work in another language. In one draft of this article I had a nice pun (if you like puns) about keeping \u201ctabs\u201d on things. 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.<\/p>\n

Example:<\/p>\n

This is the way to have one click access to all of your favorite websites. For example, you can set the Firefox home button to open your email, favorite news site and Facebook all at once.<\/p><\/blockquote>\n

When you can take something complex and break it down into simple chunks or show someone how they can make their life easier, you 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.<\/p>\n

Multiple learning styles and repetition<\/strong><\/p>\n

I want the big picture
\nGive me an example – how will this help me?
\nJust give me the steps to get it done.<\/p><\/blockquote>\n

Here we get to kill two birds with one stone. We address multiple learning styles while repeating things. If you can repeat information in different ways and use different media if possible it has a better chance of sticking in somebody’s brain. In this section of the home page article we quickly give the big picture, an example and some step-by-step instructions.<\/p>\n

Set more than one website as your home page<\/strong><\/p>\n

This is the way to have one click access to all of your favorite websites. For example, you can set the Firefox home button to open your email, favorite news site and Facebook all at once.<\/p>\n

    \n
  1. Open a new window and load up the first website you want to be your home page.<\/li>\n
  2. Click the new tab button and open the next website you want to be part of your home page group. Repeat this step until you’re done opening all the pages that you want in new tabs.<\/li>\n
  3. At the top of the Firefox window, click on the Tools menu, and select Options….<\/li>\n
  4. Select the General panel (Main panel in Firefox 3.5).<\/li>\n
  5. Click on Use Current Pages.<\/li>\n
  6. Click OK to close the Options window.<\/li>\n<\/ol>\n<\/blockquote>\n

    Assignments, Challenges, Questions<\/strong>
    \nAnother 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 have just read over them at least once to make sure you weren’t going to tell them to do anything crazy. This is an opportunity to give them a little challenge. Reading about how to do something is different than actually doing it.<\/p>\n

    Try it out: <\/strong> Go ahead and close all of your tabs and click the home button. Watch all of your chosen pages open up in tabs. Do it again; you know you want to.<\/p><\/blockquote>\n

    But people don’t read webpages!<\/strong>
    \nThey 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).<\/p>\n

    That’s all true but it doesn’t mean we can’t make those little bits that they do read engaging and effective. With practice you can do a lot with just a single sentence. The weekend before my first day at Mozilla I was reading a wiki page for new hires and 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.<\/strong>” That last little sentence did it for me. It made me laugh and I called my friend to read the paragraph back to her. It let me know that I was in the right place.<\/p>\n

    Wrapping up<\/strong>
    \nAfter the presentation we had a good discussion about the difficulties of localizing language like this. It was suggested that some good guidelines for localizers are needed and I agree. In fact my plan for this quarter is to work on the contributor documentation – especially guides for writing and localizing. This presentation is that first part of that.     So what do you think? Let\u2019s talk about it in the contributor forum.<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"

    Image by Roland Tanglao For those of you who didn\u2019t go to the Mozilla Summit (which was amazing BTW) or didn\u2019t see my presentation, I wanted to recap it for … Read more<\/a><\/p>\n","protected":false},"author":186,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[111,898],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/posts\/1196"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/users\/186"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/comments?post=1196"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/posts\/1196\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/media?parent=1196"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/categories?post=1196"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/tags?post=1196"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}