Things to consider before creating a new article

Before you run off creating new articles like a madman, let's go over some things you should consider first. These rules are not set in stone. If you have questions, you should ask them in the Articles Forum.

• What topics do we cover in the Knowledge Base?
  • Using Firefox features like tabs, bookmarks and sync.
  • Fixing problems like crashes or problems loading websites.

• What topics don't we cover in the Knowledge Base?
  • Tricks or hacks for modifying Firefox.
  • Using or recommending specific Add-ons and Plug-ins.

• Do we really need this article? – There are all kinds of things we can write about in the Knowledge Base but we want to balance how much work goes into an article (writing it, maintaining it, localizing it) with how many people it could potentially help. Our top 20 articles account for about 50% of our traffic. Often, our effort is best spent making one of those article better. Maybe what you are thinking of documenting would work best as an addition to an existing article.

Creating a new article

If you think there's an article that we need to add the Knowledge Base, here's how to get it done.

1. Go to the Articles Forum and propose creating the article.
   • Create a new thread, title it [Proposed] Name of article, and explain what the article will cover.
2. Wait for comments on your proposal. This is optional but if you intend on drafting the article yourself you might want to hear what others have to say before you do it.
3. Create and draft the article.
4. When you've finished drafting the article, add a link to it in the article thread and change the title of the thread to [Needs Review] Name of article.
   • Doing this helps to let people know that the article is waiting for review.
   • The article won't be public until it's been reviewed and approved.

Improving existing articles

The most common thing we do in the glamorous world of Knowledge Base maintenance is try to improve the articles we already have. With nearly 300 of them there's always something that can be made better. Here are three main ways to improve an article:

• Make articles easier to understand
  • Find a better way to explain something that is too complex or not very clear.
  • Add screenshots to help people understand what in the world the article is referring to. Most people probably don't know the difference between the location bar, search bar or any other bar unless it has a happy hour.
  • Add screencasts. This is the next best thing to actually grabbing the mouse out of someone's hand and doing it for them.

• Keep articles up-to-date – Major updates to Firefox always bring new features, and changes to how existing ones work. It's always best when our instructions actually match how things work in the product.

• Proof-read – Some of you have special powers to spot the mistakes that spell-check misses (how many have you noticed in this article so far?). We need your help.
  • Correct spelling, grammar and punctuation.
  • Fix issues with style and formatting. See the SUMO Style section for our guidelines.

Writing articles

There are a lot of competing things to balance when writing or editing an article. You want to be complete and concise; factual and engaging all at the same time. It's certainly not the easiest thing in the world to do. Here are some guidelines to help make that balancing act a little easier. Also, this is a wiki and it we can always revise something if we get it wrong.

Techniques for making your writing engaging

Firefox Help is a repository of technical information about the operation of the Firefox web browser application. The documentation lists the functions of Firefox's various features, troubleshooting procedures and instructions for resolving common problems. The documentation can be accessed by using the search function on each page or you can just throw your computer across the room where unicorns will use their rainbow powers to turn it into magical candy which, once consumed, will make you a level 70 computer ninja. Are you awake now? Good.

The previous paragraph sounds like a boring lecture, at least until the unicorns show up. Using humor and emotion (SURPRISE!) are some of the techniques we can use to engage people. These techniques, which I've listed below, all aim to get your brain to pay attention by recreating what this interaction could be if it were happening in person. When we do that, information is easier to understand and remember.

• Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.
• Humor and emotion – Using humor is great but it's sometimes hard or impossible to localize. Emotions like surprise and "I didn't know that!" (not sure what to call that emotion) might be easier to include.
• Multiple learning styles – Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways.
• Repetition – When you explain something in a different way with different media, you're also, obviously, repeating it which is another good way to help people remember what's important.
• Images and video – Using images and video to explain things along with text is not only the next best thing to being there to help in person, they are an easy way of including multiple learning styles and repetition.
• Activities – Especially in a tutorial, it's good to give people something useful to accomplish. It's one thing to read instructions and understand the process but it's often helpful to remind people to try things out.

The 如何設定首頁 article is a good example article that uses these techniques.

Audience

We want Firefox Help to be usable by all Firefox users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology. Assume the person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions. Also, we should assume that they haven't changed any of the default Firefox or operating system settings.

Article Names

When picking a title for an article we want to try to match what people are searching and browsing for – to match the question they might ask you in person. Here are some examples of the kinds of titles you should pick:

• For a tutorial or how-to article: How do I achieve this result? (e.g., How do I set the home page?)
• For a reference article: What is/are Feature Name? (e.g., What are App Tabs?)
• For a troubleshooting article: This is the problem I'm having (e.g., Firefox takes a long time to start up)

Organization

The general idea here is to try to build skills from simple to complex while trying to keep the information needed by most people near the top. So a simple, common solution would usually come before a complex or edge-case solution.

Introduction

Along with the title and the table of contents, the introduction is what people will use to quickly determine if they are in the right place.

• For a tutorial or how-to article: Give a brief summary of what things can be learned.
• For a reference article: Give a brief explanation of the feature.
• For a troubleshooting article: Give a brief summary of the problem and it's symptoms.

Step-by-step instructions

The main thing to keep in mind when writing step-by-step instructions is to be careful to include all the actions needed to complete the task. If, for example, you have to click "OK" after selecting a preference in order to move to the next step, be sure to include clicking OK as part of that step. Some additional things to consider:

• There are always multiple ways to achieve a result. We should always pick the most user-friendly way, i.e. using the graphical user interface and menus when possible.
• Use full sentences when describing how to access the user interface.
• Include expected results when giving instructions (e.g., Click OK and the window will close.)

Here's an example from the 如何設定首頁 article with some explanation in parenthesis.

Set a single web site as your home page

(The heading - what the steps will accomplish)

If you like to keep things simple, here’s how to set your home page in three easy steps.
(Context - shows the big picture – why are we doing this)

1. Open up the website you want to be your home page.
2. Click on the icon to the left of the web address, drag it to the Home button and then let go.
3. Click Yes to set this as your home page.

Try it out: Click the Home button and your new home page will load in the current tab. It doesn’t get much easier than that!
(Activity – give the reader an assignment and describe the expected result)

SUMO Style

In general, we should use an active, conversational style as if you are speaking with someone in person. So you should avoid saying things like, "If a user's bookmarks have been lost..." and instead say, "If you've lost your bookmarks..." Here are other common style issues you may run into when writing support articles:

Always use terms the way the appear in the Firefox interface. For example:

• Plugins does not have a hyphen.
• Add-ons has a hyphen.
• Home page is two words.

General computing terms:

• The internet is lowercase.
• Website is one word.
• Log in and log out are verbs, e.g., "Log in to the website."
• Login and logout are nouns (usually used as adjectives), e.g., "Click the login button."
• Use email instead of e-mail.
• The plural of CD-ROM is CD-ROMs.

Links to mozilla.com should not contain the locale:

• Use http://www.mozilla.com/firefox instead of http://www.mozilla.com/en-US/firefox

Avoid using the serial comma

• Use commas to separate elements in a series, but do not put a comma before the conjunction in a simple series: The flag is red, white and blue.

Capitalize the following items:

• Proper nouns
• The first word of a complete sentence
• The letters of abbreviations and acronyms unless they are normally lowercase
• The first word in numbered or bulleted lists
• The name of a key on the keyboard
• The the first word of a complete sentence following a colon
• The first word in a heading or title

Headings and Sections Our wiki is displayed using HTML5 which makes use of the <section> element. You can use the <section> element around related content. What this means for headings is that each section can have it's own outline beginning with an h1 level heading.

For the sake of clarity, avoid using i.e and e.g. If you must use them, here's a nice explanation of how it's done.

We have special visual styles for a number of items that can be achieved by adding the proper wiki markup around the item (see Kitsune Markup).

• Note
• Warning
• Code
• File names and file/paths
• Keyboard shortcuts like Ctrl + T
• Menu paths – Firefox
• Buttons

We have a special wiki markup (called "showfor") that allows you to targeting information for specific versions of Firefox or specific operating systems. For example, you display one set of instructions to people running Windows and another to people using Mac OS X (see Kitsune Markup).