How to write articles [EN]
How to write 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.
Write for a general, non-technical 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.
Pick a good title
The article title along with it's summary are the only things that the user has to judge whether or not an article will answer their question. We call this "User Confidence" and it directly impacts click through rates. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them to click through to the article.
An article's title should try to describe what the article is about. The important thing is for the first few words to be as understandable as possible, filled with keywords that are important. This will allow users to recognize what the article is about and click confidently. In addition, a title should follow these guidelines:
- Title length: Google's search results page will display up to 70 characters. Your title can be longer than this if necessary but make sure your important keywords are in the first 70 characters.
- Try to vary the way you name articles. Don't use the same verbs or phrases in every title.
- Try to not use “-ing” words.
- Do not use a colon in the article title since it prevents creating a wiki link to that article (bug 749835).
Remember that the entire explanation doesn't have to go into the title. You can use the summary to give the user additional information about what is in the article.
Fix the slug
When you create a title, SUMO will also automatically create a slug (the end of the article's URL). The slug has a 50 character limit. Spaces are rendered as dashes. The slug should be consistent with the title, but given the tighter space restraint, doesn’t need to be the same. Be sure to check the end of the auto-generated slug. Sometimes a word gets cut off or it ends in a dash. Please fix things like that.
Categories, products and topics
For the most part, an article belongs in either the How-to or Troubleshooting category. Occasionally we write "How To Contribute" articles (like this one) or something in one of the other categories.
Articles are also "relevant to" at least one product. They also belong in one main "Topic" and, optionally, a "sub-topic".
The keywords field in an article can be used to improve search results on SUMO. It should be used only under specific circumstances though, as misuse can actually hurt search. We rarely need to use keywords. For more, see When and how to use keywords to improve an article's search ranking
Write a good search summary
The article summary along with the title are the only things that the user has to judge whether or not an article will answer their question. We call this "User Confidence" and it directly impacts click through rates. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them to click through to the article.
A summary for a how-to article should include the topics covered in the article. A troubleshooting article should try to include symptoms. In addition, a summary should follow these guidelines:
- Short and to the point. Remember classified ads? Write it like that. Search engines cut off anything longer than 160 characters.
- Don't use wiki markup.
- Don't use "This article explains" in every summary. Vary it when possible. Some other phrases to consider:
- We'll show you
- We'll explain
- This page explains
- This article describes
- We'll spell out
Make 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.
Write 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.
Organize the article effectively
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.
Use descriptive heading titles
Our articles are usually comprehensive so it's important to use descriptive headings to help people find the part of the article that they need. Take a look at your table of contents. Does it work with the introduction to give you a nice overview of the scope of the article?
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 - 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 (for example, 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)
- 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.
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)
Short links are optional
We have a template used to add a mzl.la short link to the bottom of an article. This is mainly used to make it easy to include links to articles in Army of Awesome posts.
If you do include this in an article you must make sure to shorten a version of the article's URL that does not include the locale string or any extra parameters at the end.
For example, if you load Update Firefox to the latest version you may see:
You must change this before shortening to:
To create a mzl.la link:
- Past the link to an article in the shorten box at https://bitly.com
- Edit the link as described above.
- Click the button.
- Click the button on the resulting page.
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. Example: "Log in to the website."
- Login and logout are nouns (usually used as adjectives). Example: "Click the login button."
- Use email instead of e-mail.
- The plural of CD-ROM is CD-ROMs.
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
For the sake of clarity, don't use i.e. and e.g.