Confirmed users
3,193
edits
Support/KB Doc Policies: Difference between revisions
no edit summary
Michaelverdi (talk | contribs) No edit summary |
Michaelverdi (talk | contribs) No edit summary |
||
| Line 1: | Line 1: | ||
{{draft}} | {{draft}} | ||
=Article | =Article Updates= | ||
==Priorities== | |||
'''Work on articles in order of their popularity.''' Currently the top 25 articles account for over half of all views. That’s 60X the views of the bottom 25 articles (1.32M/month vs. 22K/month). This generally represents our users' priorities. The Article Tracking page can be sorted by article rank so that you can see | '''Work on articles in order of their popularity.''' Currently the top 25 articles account for over half of all views. That’s 60X the views of the bottom 25 articles (1.32M/month vs. 22K/month). This generally represents our users' priorities. The Article Tracking page can be sorted by article rank so that you can see | ||
| Line 8: | Line 9: | ||
*'''Anticipated demand''' - Occasionally we'll update an article in anticipation of a new major feature or feature change. The current article may not have a particularly high rank but we're reasonably sure based on experience and marketing plans that these articles will become popular. | *'''Anticipated demand''' - Occasionally we'll update an article in anticipation of a new major feature or feature change. The current article may not have a particularly high rank but we're reasonably sure based on experience and marketing plans that these articles will become popular. | ||
==Reviews== | |||
=Reviews= | |||
*'''Don't approve your own edits unless they are minor''' and don't essentially change the article (e.g. spelling and grammar changes, updating an image, etc.). At the very least they need to be checked for spelling and grammatical errors. | *'''Don't approve your own edits unless they are minor''' and don't essentially change the article (e.g. spelling and grammar changes, updating an image, etc.). At the very least they need to be checked for spelling and grammatical errors. | ||
*'''Pick the appropriate revision level.''' | *'''Pick the appropriate revision level.''' | ||
| Line 18: | Line 17: | ||
*'''Don't approve revisions just to give credit to someone''' - It's better to work with someone in the discussion forum to come up with a better revision. New contributors that are not participating in the discussion forum will be contacted by a SUMO admin in order to facilitate this process. '''Note:''' We need to fix the way credit works. Approved revisions based on unreviewed or rejected revisions should give everyone credit. This will eliminate the motivation for this issue. | *'''Don't approve revisions just to give credit to someone''' - It's better to work with someone in the discussion forum to come up with a better revision. New contributors that are not participating in the discussion forum will be contacted by a SUMO admin in order to facilitate this process. '''Note:''' We need to fix the way credit works. Approved revisions based on unreviewed or rejected revisions should give everyone credit. This will eliminate the motivation for this issue. | ||
=Ready for Localization= | ==Ready for Localization== | ||
'''Marking an article revision as "Ready for Localization" let's us tell localizers that the English version is done being worked on it can be translated without fear that the article will change a few more times before they're done.''' The idea is to reduce the "notification noise" and workload for localizers. Of course, if they wish, localizers can still be notified of and follow all English article changes. | '''Marking an article revision as "Ready for Localization" let's us tell localizers that the English version is done being worked on it can be translated without fear that the article will change a few more times before they're done.''' The idea is to reduce the "notification noise" and workload for localizers. Of course, if they wish, localizers can still be notified of and follow all English article changes. | ||
| Line 54: | Line 53: | ||
Archiving an article is not a one-way street. Once an article is archived we will monitor the stats, to make sure that the article wasn't a popular one. In case we made a mistake it's as easy as clicking a checkbox to get the article back on the dashboards. | Archiving an article is not a one-way street. Once an article is archived we will monitor the stats, to make sure that the article wasn't a popular one. In case we made a mistake it's as easy as clicking a checkbox to get the article back on the dashboards. | ||
=Writing Articles= | |||
==Style== | |||
= | |||
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. | 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. | ||
https://support.mozilla.com/en-US/kb/how-to-write-knowledge-base-articles | https://support.mozilla.com/en-US/kb/how-to-write-knowledge-base-articles | ||
=Screenshots and screencasts= | ==Screenshots and screencasts== | ||
'''We should make sure that articles are written to work without images or videos.''' Though both images and videos are important and greatly increase the helpfulness of an article, they can’t be mandatory. Localizers should feel free to use or delete them as they see fit. | '''We should make sure that articles are written to work without images or videos.''' Though both images and videos are important and greatly increase the helpfulness of an article, they can’t be mandatory. Localizers should feel free to use or delete them as they see fit. | ||
| Line 68: | Line 66: | ||
#'''Linux''' - use Ubuntu for screenshots. | #'''Linux''' - use Ubuntu for screenshots. | ||
=Using {for}= | ==Using {for}== | ||
'''When writing instructions for different operating systems, it's best to write complete sentences and paragraphs for each OS/Firefox version even if it means duplicating things.''' This makes the article easier to understand, maintain and localize. When it comes time, for example, to remove Firefox 3.5/3.6 specific instructions, those sections can just be deleted rather than trying to excise them from a larger section. | '''When writing instructions for different operating systems, it's best to write complete sentences and paragraphs for each OS/Firefox version even if it means duplicating things.''' This makes the article easier to understand, maintain and localize. When it comes time, for example, to remove Firefox 3.5/3.6 specific instructions, those sections can just be deleted rather than trying to excise them from a larger section. | ||