Writing guide for Knowledge Base 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 we can always revise something if we get it wrong. __TOC__ ==Who are we writing articles for?== 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. ==Picking a good title== When picking a title for an article, we want to try to match what people are searching and browsing for. Users must be able to recognize what the article is about and click confidently. It shouldn't exceed 70 characters including the suffix of its category and Firefox Help. Here are some examples of the kinds of titles you should pick: *For a tutorial or how-to article: Achieve this result (e.g., How to set the home page) *For a reference article: Feature name - main goal (e.g., App Tabs - keep favorite websites open and just a click away) *For a troubleshooting article: This is the problem I'm having - how to fix (e.g., Websites don't load - troubleshoot and fix error messages) Try not to use “-ing” words. == Fixing the slug == The slug is part of the url of the article, like: http://support.mozilla<!-- -->.org/en-US/kb/this-is-the-slug. It shouldn't exceed 50 characters. From the auto-generated slug, you can remove stop words and other unnecessary words. Make sure it stays human readable and has the most important information. == Selecting its categories, products and topics == A KB article is either an How-to or Troubleshooting article. Select also the product(s) and topic(s) it applies. ==Choosing relevant keywords == An article must be easily searchable. That's the role of keywords. All words in the title that are not stop words such as "the", "is" are already considered as keywords, so don't add them as keywords. For keywords, choose synonyms, related terms, regional versions (mainly en-UK), usual typos. DO NOT add too many keywords because each one of them will have less weight. For more info, see [[Keywords Field - Authoring KB Articles]]. * The keywords for "How do I set the home page?" should be at least start and homepage. * For "How to use bookmarks to save and organize your favorite websites", favourite is enough. * The "Clear the cache - Delete temporary Internet files to fix common website issues" article can have cash as keyword. == Filling in the summary == When filling in the summary, try to explain the goal of the article being as concise as possible. It shouldn't exceed 160 characters so that it's fully displayed in Google search results. ==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. That 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 [[How to set the home page]] article is a good example article that uses these techniques. ==Writing a good 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 its symptoms. A good introduction can usually serve as a good search summary. Often you can just copy it into the "Search result summary" field and you're done. ==How to organize the article== 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. ==How to make step-by-step instructions easy to follow== 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 [[How to set the home page]] article with some explanation in parentheses. <br><br>'''Set a single website as your home page''' <br> (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.'' <br> (Context - shows the big picture — why we are doing this) #Open up the website you want to be your home page. #Click on the icon to the left of the web address, drag it to the Home button and then let go. #Click Yes to set this as your home page. <br>'''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! <br> (Activity – give the reader an assignment and describe the expected result) == SUMO style guide == Like we talked about earlier, you should use an active, conversational style when you write. 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 they 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 uppercase. *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.org should not contain the locale:''' *Use http://www.mozilla.org/firefox instead of http://www.mozilla.org/en-US/firefox '''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 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 <nowiki><section></nowiki> element. You can use the <nowiki><section></nowiki> element around related content. What this means for headings is that each section can have its 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, [http://theoatmeal.com/comics/ie 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 the [[Markup chart|markup chart]] for a complete list).''' *{note}Note{/note} *{warning}Warning{/warning} *<code>Code</code> *{filepath File names} and {filepath file/paths} *Keyboard shortcuts like {key Ctrl+T} *Menu paths – {menu Firefox} *{button Buttons} '''We have a special wiki markup – <nowiki>{</nowiki>for<nowiki>}</nowiki> – that allows you to target 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 [[How to use For]] for details).

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 we can always revise something if we get it wrong.

Who are we writing articles for?

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.

Picking a good title

When picking a title for an article, we want to try to match what people are searching and browsing for. Users must be able to recognize what the article is about and click confidently. It shouldn't exceed 70 characters including the suffix of its category and Firefox Help. Here are some examples of the kinds of titles you should pick:

• For a tutorial or how-to article: Achieve this result (e.g., How to set the home page)
• For a reference article: Feature name - main goal (e.g., App Tabs - keep favorite websites open and just a click away)
• For a troubleshooting article: This is the problem I'm having - how to fix (e.g., Websites don't load - troubleshoot and fix error messages)

Try not to use “-ing” words.

Fixing the slug

The slug is part of the url of the article, like: http://support.mozilla.org/en-US/kb/this-is-the-slug. It shouldn't exceed 50 characters. From the auto-generated slug, you can remove stop words and other unnecessary words. Make sure it stays human readable and has the most important information.

Selecting its categories, products and topics

A KB article is either an How-to or Troubleshooting article. Select also the product(s) and topic(s) it applies.

Choosing relevant keywords

An article must be easily searchable. That's the role of keywords. All words in the title that are not stop words such as "the", "is" are already considered as keywords, so don't add them as keywords. For keywords, choose synonyms, related terms, regional versions (mainly en-UK), usual typos. DO NOT add too many keywords because each one of them will have less weight. For more info, see When and how to use keywords to improve an article's search ranking.

• The keywords for "How do I set the home page?" should be at least start and homepage.
• For "How to use bookmarks to save and organize your favorite websites", favourite is enough.
• The "Clear the cache - Delete temporary Internet files to fix common website issues" article can have cash as keyword.

Filling in the summary

When filling in the summary, try to explain the goal of the article being as concise as possible. It shouldn't exceed 160 characters so that it's fully displayed in Google search results.

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.

That 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 How to set the home page article is a good example article that uses these techniques.

Writing a good 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 its symptoms.

A good introduction can usually serve as a good search summary. Often you can just copy it into the "Search result summary" field and you're done.

How to organize the article

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.

How to make step-by-step instructions easy to follow

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 How to set the home page article with some explanation in parentheses.

Set a single website 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 we are 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 guide

Like we talked about earlier, you should use an active, conversational style when you write. 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 they 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 uppercase.
• 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.org should not contain the locale:

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

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 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 its 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 the markup chart for a complete list).

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

We have a special wiki markup – {for} – that allows you to target 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 How to use "For" tags for details).