Firefox Support Requirements Document

Project overview

One log-in for forums and knowledge base management and preferably chat as well.

• Account levels (admin, senior moderator, moderator, senior editor, editor, volunteer)

• Analytics and metrics
  • Need way to collect metrics from the content management system.
  • See SUMO Weekly Metrics

End-user navigation process

See chart and home page mock-up [1]

URL Structure

• support.mozilla.com/en-US/kb/Article+Name
• support.mozilla.com/sv/kb/Article+Name
• support.mozilla.com/en-US/chat/
• support.mozilla.com/en-US/forum/

When accessing a locale that doesn't include the requested kb page, it should fall back to en-US (or the fallback language a logged in user has specified). However, the actual URL would still be the foreign locale, and there would be a message on the page saying e.g. "This page is not yet translated to [language]. Feel free to help us out."

Technical requirements

This summarizes our technical requirements for the overall project:

• Need an automated way to collect SUMO Weekly Metrics. [2]
• Make sure TikiWiki ignores the number of empty lines before/after headings/lists/paragraphs. This helps us ensuring a consistent article format and layout regardless of the author's conventions and allows us to remove parts of the writing style guidelines. [3]
• Support for l10n URLs [4]

Knowledge base requirements

The Knowledge base is the back bone of the Firefox support platform. All known issues should be addressed, as best possible, in a user friendly knowledge base article that is easily and quickly accessible to an end-user.

Content Types

The content of the knowledge base are split up in the following two major categories:

Help

Help translates to "articles about things you can do with just Firefox", like adding a bookmark, using a keyboard shortcut, or similar. Articles under the Help category should be searchable from the Firefox built-in help window, as well as the SUMO web site. See Support below for what Help is not about.

• Reference charts: Reference charts are points of reference, that list all possible user-oriented options, like keyboard shortcuts, menu reference, command-line options, etc.
• Tutorials: Tutorials will take a feature of Firefox, and explain the very basics on how to get started using it. More advanced elements of a feature should not be included in a feature tutorial.
• How To's: How To's answer specific questions, regarding the use of Firefox, which could involve a part of a feature, or several features.

Support

Support translates to "articles about fixing problems in Firefox that require more than just Firefox, or highly technical stuff that should not be exposed to users of the built-in help". For example, how to move a profile folder, or how to configure Norton firewall to not block Firefox.

• Troubleshooting: This is the content that is more generally associated with “support” that helps users solve problems they have with Firefox. The troubleshooting section will initially be populated with MozillaZine Knowledge Base content that will be organized in a tagging structure that incorporated most frequently accessed questions data. KB style guides will allow for most user friendly help content and will evolve to include visuals.

Content Creation

Knowledge base content will be community driven. Troubleshooting content will be driven in large part by user requests, while How To content will have some initial prioritization on what the most high-leverage areas for work. Only logged-in Mozilla volunteers will be able to suggest/make changes to documents, while users will be encouraged to comment on all content—although comments will be hidden from public view initially to eliminate spam problems.

New documents

Volunteer writes documents and assigns priority for editor review

Articles are required to be reviewed, before going live. As our community grows, and we have more reviewers, we will have two separate editorial approval processes: content and style (content can be published initially if correct, even if not style guide needs to be implemented)

New articles will initially existing in a staging area, where it can be reviewed and edited, before being visible to people not logged in. Once approved for visibility to the general public, the reviewer will move the article from the staging area to the public knowledge base.

Existing documents / edits

Minor (spelling, grammar, etc): Push live

Major: Same review as new documents

All edits need to be made on a staging copy of the article. Once an edit is made, the edit is tagged for review. Contiguous edits by the same contributor will be treated as one edit. Anyone with given permission, can either approve or reject the edit. Once approved, the edit is applied to the KB version of the article. If the editor has reviewer permission, their own edit is automatically approved. Approvals and rejections are done on an edit-by-edit basis; so if there has been more than one edit to a staging copy, each edit has to be approved or rejected.

Style Guide

All Firefox support documents should be written for an audience of a slightly below average internet user (doesn’t read blogs—or at least wouldn’t know one if he saw one) and take the tone of a friendly, helpful community volunteer.

• Develop style guide for How To’s and for Troubleshooting docs
  • include requirements for any visuals (screenshots, flash/video, etc)

Feedback system

All articles will have a poll system to determine if the article is useful to users. Users are strongly encouraged to add comments on why something was not helpful, or what information would help them answer the question.

Recognition of volunteers

If user writes highly-rated article, we want to recognize their success by giving them more power to edit articles without review, and automatically approve articles they have reviewed.

Technical requirements

This summarizes our technical requirements for the knowledge base:

• Permission to make live edits to live articles should be restricted to those who have already earned our trust. There should never be incorrect information in Firefox Support KB articles.
  • Registered users should still be able to submit edits, either to bugs, or by editing a trunk version of the article, which is going to be tricky to make contributor-friendly. [5]

• Need way of knowing which staging copies are not same as live copy. [6]

• Approve and Reject buttons for reviewing article edits. [7]
  • If the editor has reviewer permission, their own edit is automatically approved. [8]
  • Approving edits should add the contributor credit to the live article. [9]

• If a page doesn't exist for the requested locale, TikiWiki should fallback according to the http accept-language header if not logged in, or according to the user preferences if logged in. [10]
  • If a page doesn't exist for the requested locale, a box should appear at the beginning of the article explaining that the page is not yet translated to the requested language. [11]

• Need a way of tracking article requests/status without using Bugzilla. [12]

• Need hidden tags for articles (needs mac review, needs style review, needs updating, etc.). [13]

• Image optimizing on upload. [14]

• We need a simple way to create a translation of an existing KB article. [15]

• Need way of finding the lowest rated articles, without having to check each article poll result individually. [16]

• Common includes which can be multi-lined, and parsed. [17]

• When a significant change is made on the en-US page, there should be a way to automatically mark all localized versions of the page as "potentially outdated". [18]
  • A "potentially outdated" localized version of an article should have easy access to the diff of the en-US. [19]
  • This "potentially outdated" status should be visible on the page as a box at the beginning of the article, even for users not logged in. [20]

• By using the same article name/id across l10n, the cross-linking of articles would be maintained without the need to update the links. For example, if the page s.m.c/sv/Article1 pointed to "Article2", the page served would be s.m.c/sv/Article2 (i.e. the Swedish version of Article2). In other words, TikiWiki will remember/save the current locale and parse in-page links accordingly. [21]

• support.mozilla.com should be able to detect what operating system the visitor is using, and automatically display a version of the content, that applies to them. In cases where the OS cannot be determined, show Windows content, by default; and always include an OS selector, near the top of each article. [22]

• Put Tiki breadcrumbs in top gray bar. [23]

• Move images to image gallery, and make upload image tool upload to the image gallery. [24]

• Need a way to link to anchors within another KB article. [25]

• Multiple instances of the same header should not produce the same anchor (breaking every TOC link after the first instance). [26]

• Need a listing of all freetags, to make tagging easier, and more consistent. [27]

• Search results should include a link to the same search, but for forums. [28]

Forum requirements

The Firefox support forums will provide users an opportunity to ask support questions that are not addressed in the KB. Users will be directed to search the KB before using the forum.

The forums will also be used as a feedback mechanism for KB articles.

The forums will be used by three types of users:

• End users seeking support (they will have already searched the KB and were unable to find a solution)
• Contributors providing support
• Administrators

Getting information out of users

Contributors need complete information from end users, but end users may not want to provide it (additional work) or may not know what to provide. Whenever possible, we should automate the information gathering. Information we could gather automatically:

• OS (from user agent)
• Firefox version (from user agent, or prompt the user if the user agent isn't Firefox)
• What the user has searched for already
• What articles the user has visited already

Other information can't be gathered automatically. We could prompt the user to include this information with separate text fields for each piece of information (like the Bugzilla Helper) or with instructional text. Not all text may apply for all situations. Information we could prompt for:

• URL
• Short description of the problem (thread title)
• Steps to reproduce
• Expected results
• Actual results
• When the problem started happening
• Configuration info such as add-ons installed
• Error text
• Screenshot

End users may reach others' threads when looking for a solution. To ensure they get the best information from this path, encourage end users to create a new thread rather than re-use someone else's thread.

Helping users find their questions later

End users will need to find their questions after posting them. Possible ways they could do so:

• Prominent link to threads they've posted in
• E-mail notification, possibly defaulted to notify
• Feed

The first two require end users to register, which they may not want to do. We should encourage them to register, but not require it. To encourage them, we should make registration very easy (a few fields on the New Question screen) and explain why it's useful to register.

Unregistered users can cause problems for contributors and administrators. Contributors can get confused by multiple anonymous users, and not requiring registration could potentially cause spam problems. To mitigate these problems:

• Force the end user to at least give themselves a name, and remember this name (via cookie?) for future posts.
• Use a captcha or similar

End users will want to not be distracted by other threads and options that may be useful to contributors. We should provide two different views - one for end users that lets them track their questions and post new ones, and one for contributors that's like a normal forum (forum list, advanced views, etc.). Which view to show could be determined by roles or at different URLs.

Helping contributors find information

Contributors want to be able to find certain threads, such as:

• Threads they've posted in.
• Threads via arbitrary criteria (advanced search).
• Threads where the user is still looking for help.
  • Allow end users to mark their question as answered and provide a filter for contributors based on this info. This could be extended to say which post answered the question, which could tie into a contributor rating feedback mechanism.
  • Threads with no replies
  • Threads where the last poster is (not) a contributor

Helping contributors help users

Contributors will be linking to KB content often when helping users, so we should make it very easy to do.

• Allow contributors to use wiki syntax (double parenthesis) for links.

Helping contributors help each other

Contributors will want to discuss things with each other that aren't support requests. Give them a forum or forums to discuss things with each other.

Technical requirements

This summarizes our technical requirements for the forums:

• Gather information automatically and manually from users when they post a question [29]
• Include text to encourage users to create new threads rather than use existing threads[30]
• Prominent link to a user's previous threads [31]
• Notify users of responses by e-mail by default.[32]
• Make it easier for users to register when creating a new question[33]
• Allow anonymous posting with captcha [34]
• Require anonymous users to name themselves [35]
• Simplified view for users [36]
• "Threads I've posted in" [37]
• Advanced search[38]
• Mark a thread as answered, and filter based on this data.[39]
• Wiki syntax [40] (FIXED)
• Create a contributors' forum (FIXED)
• Threads with no replies [41]
• Threads with last contributor response [42]
• Feed for a thread [43]

Chat requirements

Live chat will be an easy to use real time communication channel for users who can’t find answers to their questions in the knowledge base and forums. Through a web interface (no download required), users will chat with community volunteers who will be using the OpenFire application.

End-User Interface

• Users should be able to access the live chat from the browser, with no download initially.
• Users should be prompted to ask a question or tell their problem before initiating the live chat (possibly some segmentation from a drop down menu).
• The chat should appear to be a 1 to 1 communication.
• Interface should also include statements e.g.: “Don't give out personal info” (credit cards, usernames, passwords, etc).

Functionality:

• Ability to push screenshots to users during chat session
  • Way to get screenshots from users
• Allow users to get back into same chat after browser restart
• Ability to show that chat "Offline" based on idling or lack of helpers
  • Some sort of “busy” or “you are #XX in the queue” to let users know why someone is not helping them right away