How to write Knowledge Base articles TB

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 Thunderbird Help to be usable by all Thunderbird 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 Thunderbird 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 — 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 send an email?)
• For a reference article: What is/are Feature Name? (e.g., What are Plug-ins?)
• For a troubleshooting article: This is the problem I'm having (e.g., Thunderbird takes a long time to start up)

Techniques for making your writing engaging

Thunderbird Help is a repository of technical information about the operation of the Thunderbird mail client application. The documentation lists the functions of Thunderbird's various features, troubleshooting procedures and instructions for resolving common problems. The documentation can be accessed by using the search function on each page.

Use the following techniques and guidelines when you write help articles. These guidelines will help users learn how to use the software or how to solve a specific problem they are having.

• Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.
• Humor and emotion – Keep humor and emotions to a minimum. When suitable, use encouraging or helpful tips and advice in articles to help the user accomplish the task. Using humor or other emotions will not help the user and may even frustrate him or her.
• Multiple learning styles – Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways.
• Repetition – When explaining concepts or tasks in different ways, you are not only repeating it, you are helping the user retain key ideas.
• 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 Protect your Thunderbird passwords with a Primary Password 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.

Organizing 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.

Making 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 Protect your Thunderbird passwords with a Primary Password article with some explanation in parenthesis.

Changing or removing the master password
(The heading — what the steps will accomplish)

You can change or remove your master password at any time:

(Context - shows the big picture — why are we doing this)

1. At the top of the Thunderbird window, click on the Tools menu, and select Options....
2. Click the Security icon.
3. Click the Passwords tab.
4. Click Change Master Password.
5. Enter the current password to confirm you are authorized to change it.
   • If you've forgotten your master password, see Reset your Primary Password if you've forgotten it.
6. Enter the new master password twice.
   • To remove the master password, leave the new master password fields empty.
7. To accept the changed master password, click OK.
8. The master password is changed.

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 Thunderbird 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 the website(s) should not contain the locale:

• Use https://addons.mozilla.org/thunderbird/ instead of https://addons.mozilla.org/en-US/thunderbird/

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 Firefox and Thunderbird Knowledge Base markup chart for a complete list).

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

We have a special wiki markup – {for} – that allows you to target information for specific versions of Thunderbird 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 our markup guide section "SHOWFOR ", for details).