Comparer les révisions

Support Document Guide

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. __TOC__ ==Who are we writing articles for?== 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. ==Picking a good title== 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) ==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. 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. ==Writing 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 it's 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. ==How to organizing the article== 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. ==How to 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, 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. <br><br>'''Set a single web site as your home page''' <br> (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) == 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 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 '''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 '''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 its 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 the [[Markup chart|markup chart]] for a complete list).''' *{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 [https://wiki.mozilla.org/Support/Kitsune/KB/WikiSyntax this document] for more info).