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. More info here - http://mzl.la/QNLUN5

[[Video:Anatomy Intro]] This is the introduction where I give you some context for this article and a brief overview of what's in it. By doing this you can quickly determine if this is the right article for you. In this case, you want lean how to write help articles for Mozilla Support. So in this article I'll show you examples of the most common writing techniques and wiki markup that we use. You can use both the article and it's [https://support.mozilla.org/en-US/kb/anatomy-of-a-knowledge-base-article/edit wiki source] as a guide when you write. <!-- THIS IS A COMMENT. IT'S NOT VISIBLE TO THE READER BECAUSE IT HAS THOSE SPECIAL SETS OF CHARACTERS AT THE BEGINNING AND 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 kinds 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 look 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 make a table of contents --> =How to structure an article= <!-- NOTE: This is a level 1 heading --> 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. 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 end with more complicated tasks like searching and organizing. <!-- NOTE: There is another example in this paragraph of a link to an article that changes the displayed text of the link. --> ==Write descriptive section headings so readers can scan quickly== <!-- NOTE: This is a level 2 heading. Can you guess what a level 3 heading looks like? --> By naming the section after the task or solution it allows people to quickly browse the article or scan the table of contents to see the scope of the article. In some cases this may be 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 finally finding the instructions you need and then getting stranded while trying to follow them because the writer assumed you knew something you didn't. This is why we break our instructions out into complete, numbered steps. If you have to click "OK" at some point we even make that 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 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 {button Yes} to set this 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 different operating systems. We have special wiki markup that lets us show Windows instructions to Windows users and Mac instructions to Mac users. If you switch the operating system at the top of this article the steps below will change. {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. --> #At the top of the Firefox window, click on the {button Firefox} button ({menu Tools} menu in Windows XP) and then click {menu Options}. # Select the {menu General} panel. # In the Startup box, click {button Restore to Default}. #:[[Image:Home page Win3]] #Click {button OK} to close the Options window. {/for} {for mac} <!-- NOTE: These instructions are "for" Mac only. --> #On the menu bar, click on the {menu Firefox} menu and select {menu Preferences...} # Select the {menu General} panel. # In the Startup box, click {button Restore to Default}. #:[[Image:Home page Mac3]] #Close the Preferences window. {/for} {for linux} <!-- NOTE: These instructions are "for" Linux only. --> #At the top of the Firefox window, click on the {menu Edit} menu and select {menu Preferences}. # Select the {menu General} panel. # In the Startup box, click {button Restore to Default}. #:[[Image:Home page Lin3]] #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 have instructions for all operating systems in them which makes writing out steps even easier. Here are the same steps as shown above but written 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, click {button Restore to Default}. #:{for win}[[Image:Home page Win3]]{/for}{for mac}[[Image:Home page Mac3]]{/for}{for linux}[[Image:Home page Lin3]]{/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 "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 <nowiki>{</nowiki>for<nowiki>}</nowiki> markup in [[How to use For|this article]].{/note}