Compare Revisions

This article explains the different parts of a support article, such as this search summary that tells you what an article is about.

[[Video:http://youtu.be/glEfWcibcy0]] This video introduction gives you some context for the following article and a brief overview of what's in it. By watching the video you can quickly determine if this is the right article for you. '''You want to learn how to write help articles for Mozilla Support?''' This article shows you examples of our most common writing techniques and important wiki markup. You can use both the article and its [https://support.mozilla.org/en-US/kb/anatomy-of-a-knowledge-base-article/edit wiki source] as a guide when you write an article. <!-- THIS IS A COMMENT. IT'S NOT VISIBLE TO THE READER BECAUSE IT HAS THOSE SPECIAL SETS OF CHARACTERS AT THE BEGINNING AND AT THE END. Occasionally authors leave notes for each other this way. In this article I'll use these to point out how we use wiki markup. --> In general, we have two basic types of articles with two kinds of introductions: *Tutorial or "how-to" articles: A brief summary of the feature or task and what things can be learned ([[Use tabs to organize lots of websites in a single window|example]]). *Troubleshooting articles: A brief summary of the symptoms and possible solutions ([[Firefox keeps crashing at startup|example]]). <!-- NOTE: In the paragraph above, asterisks, *, are used to create an unordered list. Also a link to another article normally looks like [[Name of article]] but in this case I added a pipe, |, and a new name, so that they look like [[Name of article|what I want to display to the reader]] --> __TOC__ <!-- NOTE: That's how you create a Table of Contents --> = How to structure an article = <!-- NOTE: This is a level 1 heading --> The general idea here is to try and 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. == Write descriptive section headings so readers can scan through quickly == <!-- NOTE: This is a level 2 heading. Can you guess what a level 3 heading looks like? --> Naming the section header after the task or the solution allows the reader to quickly browse the article or scan the table of contents to see the scope of the article. In some cases this may already provide enough information for some users and they wouldn't even need to read the rest of the article. = Create step-by-step instructions = There's nothing more frustrating than to finally find the instructions you need and then get stranded while trying to follow them because the writer assumed you knew something you didn't. This is why we break our instructions down into complete, numbered steps. If you have to click "OK" at some point we even define that as a step. Here's an example from the [[How to set the home page]] article: <!-- The sentence above has another example of a regular link to an article. --> # Open the web page you want to use as your home page. # Drag and drop that tab onto the Home button [[Image:Fx89HomeButton]] on your toolbar. #;[[Image:Fx89 Set homepage drag-and-drop]] # Click {button Yes} on the prompt to set this page as your home page. <!--Look at the wiki markup in this step. It creates a special style to denote a button on the screen. --> {note}'''Tip:''' Look at the [https://support.mozilla.org/en-US/kb/anatomy-of-a-knowledge-base-article/edit wiki source] to see how it's done.{/note} <!-- Notes don't have to be called "Notes" all the time. Occasionally they're more like tips so we'll use "Tip" instead. --> = Create instructions for different operating systems or versions of Firefox = Often Firefox instructions are different for the different operating systems. We have special wiki markup that shows Windows instructions to Windows users, Linux instructions to Linux users, and Mac instructions to Mac users. If you switch the operating system in the "Customize this article" box to the right, the instructions below will change according to the selected operating system. This example is from the [[Find what version of Firefox you are using]] article. {for win,linux}<!-- This is "for" Windows and Linux only -->Click the menu button [[Image:Fx89menuButton]], click {menu Help} and select {menu About Firefox}.{/for}{for mac}<!-- This is "for" Mac only -->On the menu bar, click the {menu Firefox} menu and select {menu About Firefox}.{/for} The About Firefox window will appear. The version number is listed underneath the Firefox name. {note}'''Tip:''' Look at the [https://support.mozilla.org/en-US/kb/anatomy-of-a-knowledge-base-article/edit wiki source] to see how it's done. You can learn more about using <nowiki>{</nowiki>for<nowiki>}</nowiki> markup in [[How to use "For" tags|this article]].{/note} = Use templates in your instructions = There are a lot of common steps in Firefox articles. For these we create "templates" so that we don't have to write (and translate) them over and over again. Usually templates include instructions for all operating systems which simplifies and accelerates the writing of the steps a lot. This example from the [[How to set the home page]] article includes a template that gives instructions for opening the Firefox Settings panel. #<!--This is a template -->[[T:optionspreferences]] #Click the {menu Home} panel.<br>[[Image:Fx91HomePanel]] #Click the menu next to ''Homepage and new windows'' and choose to show the default Firefox Home page, custom URLs or a blank page. <!-- NOTE: In this section, the template includes the instructions for all operating systems (the only part we may need to worry about is the screenshot.) --> {note}'''Tip:''' Look at the [https://support.mozilla.org/en-US/kb/anatomy-of-a-knowledge-base-article/edit wiki source] to see how it's done. See [[Using Templates]] to learn more about templates.{/note} = Knowledge Base guidelines = For more guidelines on Knowledge Base contribution, see [https://support.mozilla.org/en-US/products/contributor/kb this page].