Comparer les révisions

editing, markup, guide

Describes the expected subject matter for Knowledge Base documents and the writing style and tokens to be used to edit them.

Thanks for helping with our support articles. For about four million people a week, these articles are the face of Mozilla when they have a problem or question about Firefox. The work you do here has a huge impact on people all over the world. As a nonprofit, open-source project, we rely on volunteers to write the majority of the articles. You don't need special permission to work on them – this is a wiki that anyone can edit. This article is a general guide to writing and editing support documents. If you have questions about any of this, you can just [mailto:&#109;&#118;&#101;&#114;&#100;&#105;&#64;&#109;&#111;&#122;&#105;&#108;&#108;&#97;&#46;&#99;&#111;&#109; email me], Michael, your friendly neighborhood Support Content Manager. __TOC__ <section> = Things to consider before creating a new article = Before you run off creating new articles like a madman, let's go over some things you should consider first. These rules are not set in stone. If you have questions, you should ask them in the [https://support.mozilla.com/en-US/forums/knowledge-base-articles Articles Forum]. *'''What topics do we cover in the Knowledge Base?''' **Using Firefox features like tabs, bookmarks and sync. **Fixing problems like crashes or problems loading websites. *'''What topics don't we cover in the Knowledge Base?''' **Tricks or hacks for modifying Firefox. **Using or recommending specific Add-ons and Plug-ins. {note}Troubleshooting articles are often an exception to these rules. If a common problem can only be fixed by with a "hack" or by installing a particular Add-on, we'll document that.{/note} *'''Do we really need this article?''' – There are all kinds of things we can write about in the Knowledge Base but we want to balance how much work goes into an article (writing it, maintaining it, localizing it) with how many people it could potentially help. Our top 20 articles account for about 50% of our traffic. Often, our effort is best spent making one of those article better. Maybe what you are thinking of documenting would work best as an addition to an existing article. </section> ---- <section> = Creating a new article = If you think there's an article that we need to add the Knowledge Base, here's how to get it done. #Go to the [https://support.mozilla.com/en-US/forums/knowledge-base-articles Articles Forum] and propose creating the article. #*Create a new thread, title it <nowiki>[Proposed]</nowiki> Name of article, and explain what the article will cover. #Wait for comments on your proposal. This is optional but if you intend on drafting the article yourself you might want to hear what others have to say before you do it. #[https://support-stage.mozilla.com/kb/new Create] and draft the article. #When you've finished drafting the article, add a link to it in the article thread and change the title of the thread to <nowiki>[Needs Review]</nowiki> Name of article. #*Doing this helps to let people know that the article is waiting for review. #*The article won't be public until it's been reviewed and approved. </section> ---- <section> = Improving existing articles = The most common thing we do in the glamorous world of Knowledge Base maintenance is try to improve the articles we already have. With nearly 300 of them there's always something that can be made better. Here are three main ways to improve an article: *'''Make articles easier to understand''' **Find a better way to explain something that is too complex or not very clear. **Add screenshots to help people understand what in the world the article is referring to. Most people probably don't know the difference between the location bar, search bar or any other bar unless it has a happy hour. **Add screencasts. This is the next best thing to actually grabbing the mouse out of someone's hand and doing it for them. *'''Keep articles up-to-date''' – Major updates to Firefox always bring new features, and changes to how existing ones work. It's always best when our instructions actually match how things work in the product. *'''Proof-read''' – Some of you have special powers to spot the mistakes that spell-check misses (how many have you noticed in this article so far?). We need your help. **Correct spelling, grammar and punctuation. **Fix issues with style and formatting. See the SUMO Style section for our guidelines. </section> ---- <section> =Writing 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 it we can always revise something if we get it wrong. ==Techniques for making 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. The previous 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. ==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. ==Article Names== 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 set the home page?) *For a reference article: What is/are Feature Name? (e.g., What are App Tabs?) *For a troubleshooting article: This is the problem I'm having (e.g., Firefox takes a long time to start up) ==Organization== 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. ==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 it's symptoms. ==Step-by-step instructions== 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 [[How to set the home page]] article with some explanation in parenthesis. ===Set a single web site 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.'' <br> (Context - shows the big picture – why are we 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. <br>'''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! <br> (Activity – give the reader an assignment and describe the expected result) </section> ---- <section> = SUMO Style = In general, we should use an active, conversational style as if you are speaking with someone in person. 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 the 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 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 mozilla.com should not contain the locale:''' *Use http://www.mozilla.com/firefox instead of http://www.mozilla.com/en-US/firefox '''Avoid using the serial comma''' *Use commas to separate elements in a series, but do not put a comma before the conjunction in a simple series: ''The flag is red[,] white and blue.'' '''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 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 <nowiki><section></nowiki> element. You can use the <nowiki><section></nowiki> element around related content. What this means for headings is that each section can have it's 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, [http://theoatmeal.com/comics/ie 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 [[Kitsune Markup]]).''' *{note}Note{/note} *{warning}Warning{/warning} *<code>Code</code> *{filepath File names} and {filepath file/paths} *Keyboard shortcuts like {key Ctrl+T} *Menu paths – {menu Firefox} *{button Buttons} '''We have a special wiki markup (called "showfor") that allows you to targeting information for specific versions of Firefox 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 [[Kitsune Markup]]). </section>