SUMO Blog

Helping users troubleshoot crashes has always been a hard thing to document in the knowledge base. We try to help the user better define the circumstances of their crash, then list possible causes and solutions for those circumstances. An (obviously) unintended consequence is that there is so much information to digest, it confuses users.

The problem is that if Firefox crashes, it could be for any number of reasons. The range of causes and volume of troubleshooting is so great that we end up doing more to try help the user navigate crash documentation, than offer a solution. In most cases the solution is vague and not very helpful, which confuses users even more.

Each Firefox crash reported to Mozilla using the Mozilla Crash Reporter has a crash ID and lists the type of crash, called the crash signature. Usually, each crash signature has a much more specific cause/solution. Instead of asking users to define each circumstance of their crash, they can get to the solution more quickly if we ask for the crash signature, then provide a document for each crash sig.

What we’ve done is turned our Firefox crashes article into a tutorial on accessing your crash report via about:crashes. At the top right corner of each crash report on crash-stats.mozilla.com, you’ll notice that there is a [Get Help] button. What that does is search support.mozilla.com for the crash signature from the report.

By creating an article for each crash signature, and putting the crash signature in the article content, the Get Help button on crash-stats.mozilla.com will provide the user a link to the article that addresses their specific type of crash.

Naturally, there are a lot of crash signatures. We can’t provide an article for every crash. However, we can get a list of the most common crash signatures, and try to make sure the 10 most common crashes have articles in the knowledge base. Ever since Firefox 3.5 was released, we have been keeping an eye on the top Firefox 3.5.x crashes, and adding them to a list here.

What we need now is people to draft an article for each crash sig. There is a bug link for each crash sig on the list, that contains details about known causes/solutions for each crash. If you need help creating articles, we have a contributor page about creating articles. For any further help, just ask in the Contributors forum.

Back in May, we came together and worked on a user manual for Firefox as part of the FLOSS Manuals Project, an open-source book publishing project. It was a huge success and we now have a great Firefox Manual you can download, read online or get as a nicely bound paper copy.

Now that Firefox 3.5 is out, it’s time to upgrade the manual as well. As a community, we’ll be getting together and making sure that the new manual reflects all the changes and improvements that went into this new browser and that all the content is current. It’d be great to have you join us and help make sure the manual is up to date.

When?

Thursday, July 16 at 10 AM Pacific time, 1 PM Eastern time, 19:00 Central European time. If you’re in Europe or Asia and want to start earlier, you are of course more than welcome to!

Where and how?

1. Register to get an account at the FLOSS Manual site.
2. Go to the Write section of the Firefox Manual.
3. Pick a chapter that you want to read, click the “edit” link, and start updating it!

On the right side of the website is a chat window where you will be able to chat with other participants.

What needs to be done?

Many pages need just small updates, new screenshots or changes to be updated for Firefox 3.5. Here are just some of the things that you can do:

• Update number of users and number of locales on the Introduction page
• Update graphics (number of total users) on the Open Source page
• Mention this sprint in the page about the manual
• Update screenshots in all chapters
• Discuss new Clearing Recent History features (A new chapter replacing part of this one on the URL)
• Discuss new Private Browsing features (may integrate with above)
• Discuss new features (tab tearing) in the Tabbed browsing page
• Read through full manual to correct minor changes

Just 20 minutes of your time will help keep our documentation relevant, current and useful for all Firefox users, and by making edits, your name will forever in the Credits section of both the online and paperback version.

See you Thursday!

In March, I posted about using article feedback to improve knowledge base articles and the importance of making knowledge base articles easy to read; but those are specific areas that are part of a greater knowledge base goal, which is to make the process of Firefox self-help as easy as possible.

There are few sources of information to we draw from:

• Top searches: The most common search terms in the SUMO Weekly metrics document.
• Weekly common issues: Our Weekly Common Issues page tracks the most common support issues each week.
• Article polls: At the bottom of each article, there are poll questions: “Did this article solve a problem you had with Firefox?“, “Was this article easy to understand?“, and “Please rate your experience with solving your problem on support.mozilla.com from 1 to 5” (For more precise data there’s the PageView Data.)
• And of course, Article comments: There is a text field on each article for users to provide feedback about the article. When logged in as a contributor, that feedback is displayed at the bottom of the article.

Here’s how that data is utilized to measure the quality of the knowledge base, and make it better:

The top search terms are tested to find out if the first search results contain the article the user is most likely searching for.
If they don’t:

• The correct article may need to be renamed to match the search term.
• The top article in search results may be mistaken for a different issue; so a link to the correct article is added in the intro of the first search result. If users are being redirected to the correct article, the poll data should improve.
• Keywords that match the search terms are added to the correct article.

For generic search terms the article comments for each result may clarify what users are asking about.

The weekly common issues page is checked for any items that need documentation in the knowledge base. If enough information is available to create documentation, the relevant articles are updated or a new article is created.

The comments in articles with the lowest understandability score are checked to get details on what is not understandable in the article, so we can assess what can be done to eliminate that confusion. Sometimes that means rewording or reformatting the article. In some cases it is a matter of adding screenshots. In other cases, it’s a matter of streamlining or purging the article to simplify it for users.

In the end, it’s about taking the data, analyzing why the data is what it is, and what we can do to improve each issue. As a result, the article poll scores should go up, and users will get answers to their questions about using Firefox. We’ve outlined these tests in a contributor page, so everyone as a community can be most affective in making the knowledge base better each week. You can post any suggestions for improvement in the Contributors forum.

To say that the SUMO knowledge base is just a wiki really doesn’t do it justice. While it’s very easy to start contributing to the knowledge base and simply assume that it works just like many other wikis (e.g. Wikipedia), there are a number of characteristics of SUMO tailored toward user support which make it different. This can be both a blessing and a curse. We need to understand how SUMO is different; but once we are familiar with it, the community has better tools to provide better user support.

If you’re a new knowledge base contributor, please read our new How we are different page, which lists the differences between SUMO and other wikis and gives an overview of why we are different. New knowledge base contributors will also be able to find a link to that page in our introduction to contributing to the knowledge base.

This is also part of our response to localizer feedback, which we have been continually gathering from active SUMO localizers. Remember that if you are a SUMO localizer and would like to meet with us, just contact us on this blog or post in the Contributors forum.

Firefox 3.5 Release Candidate 2 has been released, which means that you can now start updating screenshots in the knowledge base for Firefox 3.5! As a quick reminder, here are the guidelines on updating screenshots for 3.5:

• Screenshoots should only be shown for the specific the operating system. If it’s a Windows screenshot, make sure it only shows for Windows users. The existence of Windows screenshots gives Mac users the wrong impression that the article content only applies to Windows. To make content only display for certain operating systems and versions of Firefox, the instructions are in the contributor page called Using SHOWFOR.
• Don’t let the total size of all screenshots in the article (including all operating systems) get above 200K. Crop or resize whenever possible; and if you resize the image, save it as a jpg file. If you need to remove previous images, remove in this order:
  1. Firefox 2.0/Mac
  2. Firefox 2.0/Linux (although there shouldn’t be any)
  3. Firefox 2.0/Windows
  4. Firefox 3.0/Mac
  5. Firefox 3.0/Linux (although there shouldn’t be any)
  6. Firefox 3.0/Windows
• After updating screenshots on an article, update the Firefox 3.5 article tracker page so we know which articles are done.

Of course, the rest of the guidelines on our Adding screenshots page always apply. For most articles, any screenshots of the Options window will need updating because the Privacy icon has changed; and screenshots of the tab bar will also need to be updated because the New Tab button has moved since Firefox 3.0. If you have any questions, just post them in the Firefox 3.5 knowledge base status update thread in the Contributors forum. Thanks a lot!

One issue that sometimes confuses Knowledge Base contributors is knowing what levels of permission each user group on SUMO has. For instance, someone may be able to edit one category or articles, but not another. We now have documented it in a Group permissions page, which you can find linked on the Contributor Home Page.

In short, if you are registered you are considered a contributor. The Approvers group are contributors who have reached the point where they can be trusted on the system. The locale leaders group are contributors who are in charge of the support localization effort for a specific locale.

As part of our response to localizer feedback, we want to make sure the differences are listed and available for everyone to see. If you have any questions or suggestions, please comment on this blog post or in the Contributors forum. Thanks!

Last week, the fixes for SUMO 1.1 were applied to support.mozilla.com. The big news: SUMO now supports screencasts! A screencast is a video recording of a computer screen. In the same way that images of a computer screen (i.e. screenshots) are helpful in illustrating what Firefox support instructions are referring to, screencasts go a step further by showing users what the actions of those instructions look like.

Firefox 3.0.x users will be able to view screencasts in Flash format, but we also support the open video format called Ogg/Theora. Firefox 3.5 users will be able to view Ogg/Theora videos without the need for a plugin. For more information about open video, read In Support of Open Video.

What makes screencasts on SUMO especially great is that the SUMO knowledge base is a wiki. Adding a screencast to an article can be done by anyone! (That means you!) We have provided a tutorial on adding screencasts to the knowledge base, with a list of software you can use to create them. Adding of screencasts is fully integrated with the article editor; so if you know how to edit a knowledge base article, you know how to add a screencast. If you need any help adding screencasts, you can always ask in the Contributors forum. And the next time you’re having trouble explaining something about how to use Firefox, you’ll be able to show them.

With Firefox 3.5 rolling off the presses, it’s time for the long-awaited Support Firefox Day. We’re planning on having the event June 25th at 10 AM PDT (1 PM EDT).

At this event, we’ll be talking about Firefox 3.5, supporting the fastest Firefox ever and how Firefox support has grown along with the browser. There will be a preview of some of the new Firefox 3.5 features, with live demos and Q&A. We’ll also be going over the new screencasts feature in SUMO as well as some tips and resources for helping. At the end of the session, we’ll all get together and spend a couple hours answering questions on the support forums. If you’ve never done Firefox support before or are just curious to learn about how it works at Mozilla, this is a fun and interactive way to get involved.

You can get all the details and sign up for the event at the Support Firefox Day main page.

See you there!

It’s been a while since our last post about updating the knowledge base for Firefox 3.5. It’s especially a good time to get involved, now that Firefox 3.5 development is getting close to a release candidate.

We’ve already made great progress! support.mozilla.com has been updated and now supports marking knowledge base content specific to 3.5.  The Options window article and some other articles were then reorganized to make the transition easier.  As a community, we’ve been keeping track of changes to Firefox and many of the new features in Firefox 3.5 already have new articles.  Now, we have to just do to following to finalize the knowledge base:

1. The first thing to do is to through the items on our Updating articles for 3.5 page, and make sure each of those updates is done. If you see one that hasn’t been done, please help make the edit.
2. Thanks to support-conscious developers, relevant changes to Firefox 3.5, have been marked with the keyword “user-doc-needed”. We’d also like your help going through this list of user-doc-needed bugs, and making sure the knowledge base reflects these changes.  Once a change has been made, change the keyword to user-doc-complete and comment in the bug with a link to the documentation.
3. Lastly, we will do a full audit of the en-US knowledge base. It’s a great way to refresh your knowledge of Firefox and isn’t very time consuming. Essentially, it’s just going through each article and asking:
   • Does it apply to Firefox 3.5? If so, the “Firefox 3.5″ category should be check marked in the article editor.
   • Does it need to be updated/changed for Firefox 3.5? If so, update it accordingly, check mark the Firefox 3.5 category for the article, and check mark the “Alert translators” box.
   • Do the screenshots need to be updated for Firefox 3.5? If so, just post to our tracking page, but don’t update the screenshots yet. We will wait until there’s a release candidate and the interface is finalized before adding screenshots.

Once all of that is done, knowledge base localizers should have a solid en-US foundation of changes to translate in time for the Firefox 3.5 release, without having to worry about changes being translated prematurely.

On the whole, most changes revolve around privacy information, tabbed browsing, and small text changes. For user support contributors, now is the time to get acquainted with Firefox 3.5. When Firefox 3.5 is released, there is going to be a large volume of users asking questions about it. It’s the second most wonderful time of the year!

As we constantly try to improve the support experience for both Firefox users and the wonderful contributors who help them, it’s good to take time to see how we’re doing. As such, we just launched a series of surveys asking our contributors about how they use the forums and live chat, what we’re doing well and where we can make improvements. You should have gotten an e-mail from us with your survey link. Please take the time to fill it out — it’ll take only a couple minutes and will really help us in making support fun and rewarding for everyone.

If you’re interested in support or SUMO and didn’t receive an e-mail, just let us know your e-mail address and we’ll be sure to have a survey sent out ASAP.