Compare Revisions

You've got 160 characters plus the title to let people know what the article is about. It's like a tweet or classified ad.

[[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" article intros: 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 article intros: A brief summary of the symptoms and the solution ([[Flash 11.3 crashes|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|name 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. For example, in this [[Use Tab Groups to organize a lot of tabs|Tab Groups]] article we ''start'' with why you should use the feature, then ''move on'' to how to make a group and ''finish'' with more complicated tasks like searching and organizing. <!-- NOTE: There is another example in this paragraph, showing a link to an article that changes the displayed text of the link. --> == 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 a tab with the web page you want to use as your home page. # Drag and drop that tab onto the Home button [[Image:Home Button]]. #;{for winxp}[[Image:Home Page 29 - WinXP]]{/for}{for win7,win8}[[Image:Home Page 29 - Win8]]{/for}{for mac}[[Image:Home Page 29 - Mac]]{/for}{for linux}[[Image:Home Page 29 - Linux]]{/for} # Click {button Yes} to set this page as your home page. <!-- NOTE: Look at the wiki markup in this step that creates a special style to denote a button on the screen. --> == 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 and Mac instructions to Mac users. If you switch the operating system at the top of this article, the appropriate steps below will change according to the selected operating system. {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 (please don't actually change the article though).{/note} <!-- NOTE: Notes don't have to be called "Notes" all the time. Occasionally they're more like tips so we'll use "Tip" instead. --> {for win} <!-- NOTE: These instructions are "for" Windows only. --> # Click the menu button [[Image:New Fx Menu]] and choose {button Options}. # Select the {menu General} panel. # In the Startup box under ''Home Page:'' click {button Restore to Default}. #;[[Image:HomePage-Fx34Win]] # Click {button OK} to close the Options window. {/for} {for mac} <!-- NOTE: These instructions are "for" Mac only. --> # Click the menu button [[Image:New Fx Menu]] and choose {button Preferences}. # Select the {menu General} panel. # In the Startup box under ''Home Page:'' click {button Restore to Default}. #;[[Image:HomePage-Fx34Mac]] # Close the Preferences window. {/for} {for linux} <!-- NOTE: These instructions are "for" Linux only. --> # Click the menu button [[Image:New Fx Menu]] and choose {button Preferences}. # Select the {menu General} panel. # In the Startup box under ''Home Page:'' click {button Restore to Default}. #;[[Image:HomePage-Fx34Lin]] # Click {button Close} to close the Preferences window. {/for} === Use templates in your step-by-step 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 single steps a lot. Here are the same steps as shown above but this time written by using templates. {note}'''Tip:''' Be sure to 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 (please don't edit anything though).{/note} # [[T:optionspreferences]] # Select the {menu General} panel. # In the Startup box under ''Home Page:'' click {button Restore to Default}.<br>{for win}[[Image:HomePage-Fx34Win]]{/for}{for mac}[[Image:HomePage-Fx34Mac]]{/for}{for linux}[[Image:HomePage-Fx34Lin]]{/for} # [[T:closeOptionsPreferences]] <!-- NOTE: In this section the templates include the instructions for all operating systems. So the only part we need to worry about is the screenshot. It's important to remember that when you use a "for" markup in a list you can ONLY USE IT IN ONE STEP AT A TIME. YOU CAN NOT MAKE A STEP FOR ONE OPERATING SYSTEM AND NOT FOR ANOTHER. THE NUMBERING AND SPACING WILL BREAK. IN THAT CASE YOU WILL HAVE TO MAKE SEPARATE LISTS LIKE IN THE EXAMPLE IN THE PREVIOUS SECTION. More info in this article http://support.mozilla.org/kb/how-to-use-for --> {note}'''Note:''' [https://support.mozilla.org/en-US/kb/category/60 This is a list of all of our templates.] And you can learn more about using the <nowiki>{</nowiki>for<nowiki>}</nowiki> markup in [[How to use For|this article]].{/note}