Rules and guidelines: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
mNo edit summary
(*** near total rewrite of the rules ***)
Line 1: Line 1:
We now have brand spanking new rules for editing!  Please check out [[Talk:Rules]] for a discussion of how and why the rules have changed.
Please check out [[Talk:Rules]] for a discussion of how and why the rules have changed.


==Before Creating a New Article==
Before you create a new article in the knowledge base, check to see if the topic hasn't already been covered somewhere. Do a search and browse the relevant sections. Even though it might seem logical to you that a certain topic would be located in <nowiki>[[Firefox : FAQs]]</nowiki>, for example, it might actually be located in <nowiki>[[Firefox : Tips]]</nowiki>. Check first before making a new article.
==Naming Conventions==
==Naming Conventions==
In general, try to use [http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions Wikipedia's Naming conventions] except for cases where we have determined that our naming conventions should be different.
In general, try to use [http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions Wikipedia's Naming conventions] except when these differ from what is described below.
* Unless the term you wish to create a page for is a proper noun or is otherwise almost always capitalized, do not capitalize second and subsequent words.  Initial capitalization does not matter, as the Wiki software always capitalizes the article title's first letter.
===Capitalization===
* Categories are shown off by using a "slash" (/) with no spaces.
* Use capital letters for the first letter of each main word in a title.
**Good: <nowiki>[[Firefox/Profile|Profile]] (when on a page relating to Firefox, just [[/Profile|Profile]])</nowiki>
**Good: <nowiki>[[Thunderbird : FAQs: Open in Inbox]]</nowiki>
**Bad: <nowiki>[[Firefox : Tips : Profile]]</nowiki>
**Bad: <nowiki>[[Thunderbird : FAQs: Open in inbox]]</nowiki>
* When possible, use just a simple article title and remove any existing Categorical structure. (<nowiki>[[DOM Inspector]] is better than [[Dev/DOM Inspector]]</nowiki>)  Putting a category in the name doesn't really help us find the article. If we do this right, a simple Search should turn up the article, or better yet just hitting "Go" will take you to the precise article you're looking for, because if it has a simple name you don't need to know the Category it is in.
===Categorization===
* When possible, use short page titles. This eases linkability and avoids the current layout bug of long titles overlapping the search box.  There's no need for a link to include the entire grammatically complete form of a question, especially when two descriptive words would suffice. Following the example above:
* Especially for articles dealing with Firefox, Thunderbird, and the Suite, categorize new articles by using colons (with a space before and after each) rather than with slashes (/) and no spaces.  
** Bad: [[Firefox : Tips : Where is the profile stored on different operating systems and how do I change the location]]  
**Good: <nowiki>[[Firefox : Tips : Profile]]</nowiki>
* Application Name links should only use the App Name, not "Mozilla App Name" except the Suite, which should be linked to and called "Mozilla Suite", not "Mozilla", "Suite", "Seamonkey", or any other name.
**Bad: <nowiki>[[Firefox/Profile|Profile]]</nowiki>
* Layout issues or other things should use Gecko as the App NameWhen something affects more than one app in a way that it would be wasteful to split up the articles because they would be practically identical, dispose of the Categories, and just have the plain article title. Only split up the articles by App Category if confusion would result from a united page because the information does not really overlap.
* If you are uncertain about what category to use, then look at other articles and try to follow the conventions they use. Because the knowledge base contains articles for the Suite, Firefox, and Thunderbird (and more!), it is generally important to provide some degree of categorization, particularly since users sometimes find articles via search. If the page title does not indicate which product the article is for, it can be confusing for end-users.
 
* In some cases, such as when an article applies to two or more products (Firefox, Thunderbird, or the Suite), it may be best to use no catgorization at all. The <nowiki>[[Profile Folder]]</nowiki> article is a good example of this.
==Specificity==
===Use Short Titles===
* For the Suite, we have to decide how granular to get, and if we want to futher break things down by component (Browser/Mail and News/Editor/Chatzilla).
* When possible, use short page titles. This eases linkability and avoids the current layout bug of long titles overlapping the search box.  There's no need for a link to include the entire grammatically complete form of a question, especially when a few descriptive words would suffice.  
** Bad: <nowiki>[[Mozilla Suite : Tips : Use Send Page or Send Link to tell your friends about a great webpage]]</nowiki>
**Good: <nowiki>[[Mozilla Suite : Tips : Send Page or Link]]</nowiki>
===Application Names===
* Application name links should only use the application name, such as "Firefox" or "Thunderbird", not "Mozilla Firefox" or "Mozilla Thunderbird". The exception is the Suite, which should be linked to and called "Mozilla Suite", not "Mozilla", "Suite", "Seamonkey", or any other name.
** Bad: <nowiki>[[Mozilla Firefox: FAQs: Bookmarks]]</nowiki>
** Bad: <nowiki>[[Suite : Issues: Profile Locked]]</nowiki>
* Layout issues or other things should use Gecko as the application nameAs noted above, when an article applies to more than one application in a way that it would be wasteful to split up the articles because they would be practically identical, it may be best to dispose of the categories and just have the plain article title.  


==Editing Courtesy==
==Editing Courtesy==
* Any time you edit a page, please add a short comment in the "Summary" field about the change you made. This makes it easier for others to see what has changed. Importantly, it can help make it easier for us to distinguish knowledge base spamming/vandalism from legitimate contributions.
* If you find yourself wanting to change an entry back to an earlier revision, ask yourself if the current version had a useful purpose, and whether it really is necessary to change it back.   
* If you find yourself wanting to change an entry back to an earlier revision, ask yourself if the current version had a useful purpose, and whether it really is necessary to change it back.   
* Document reasons for potentially controversial changes on the Talk pages.
* Document reasons for potentially controversial changes on the Talk pages.
* Accept changes to your entries in a spirit of helpfulness.   
* Accept changes to your entries in a spirit of helpfulness.   
* We should have a protocol for when someone consistently makes certain types of mistakes or formatting quirks.  Place a message in their User page? Email directly?
* If someone consistently makes certain types of mistakes or formatting quirks, consider placing a message in their User page.
==Superfluous Information==
* In knowledge base articles, do not insert signatures, links to sites that are not related to Mozilla products, or other superfluous information. If you want to give a link to your own personal website, for example, then put it in your User page, not in the article. In short, if the information or link is not directly related to the topic of the article, then don't include it in the article.
* Of course, signatures are welcome (even helpful) in the Talk pages, so do not hetitate to use them there.


==Test Editing Pages==
==Test Editing Pages==

Revision as of 15:39, 26 October 2004

Please check out Talk:Rules for a discussion of how and why the rules have changed.

Before Creating a New Article

Before you create a new article in the knowledge base, check to see if the topic hasn't already been covered somewhere. Do a search and browse the relevant sections. Even though it might seem logical to you that a certain topic would be located in [[Firefox : FAQs]], for example, it might actually be located in [[Firefox : Tips]]. Check first before making a new article.

Naming Conventions

In general, try to use Wikipedia's Naming conventions except when these differ from what is described below.

Capitalization

  • Use capital letters for the first letter of each main word in a title.
    • Good: [[Thunderbird : FAQs: Open in Inbox]]
    • Bad: [[Thunderbird : FAQs: Open in inbox]]

Categorization

  • Especially for articles dealing with Firefox, Thunderbird, and the Suite, categorize new articles by using colons (with a space before and after each) rather than with slashes (/) and no spaces.
    • Good: [[Firefox : Tips : Profile]]
    • Bad: [[Firefox/Profile|Profile]]
  • If you are uncertain about what category to use, then look at other articles and try to follow the conventions they use. Because the knowledge base contains articles for the Suite, Firefox, and Thunderbird (and more!), it is generally important to provide some degree of categorization, particularly since users sometimes find articles via search. If the page title does not indicate which product the article is for, it can be confusing for end-users.
  • In some cases, such as when an article applies to two or more products (Firefox, Thunderbird, or the Suite), it may be best to use no catgorization at all. The [[Profile Folder]] article is a good example of this.

Use Short Titles

  • When possible, use short page titles. This eases linkability and avoids the current layout bug of long titles overlapping the search box. There's no need for a link to include the entire grammatically complete form of a question, especially when a few descriptive words would suffice.
    • Bad: [[Mozilla Suite : Tips : Use Send Page or Send Link to tell your friends about a great webpage]]
    • Good: [[Mozilla Suite : Tips : Send Page or Link]]

Application Names

  • Application name links should only use the application name, such as "Firefox" or "Thunderbird", not "Mozilla Firefox" or "Mozilla Thunderbird". The exception is the Suite, which should be linked to and called "Mozilla Suite", not "Mozilla", "Suite", "Seamonkey", or any other name.
    • Bad: [[Mozilla Firefox: FAQs: Bookmarks]]
    • Bad: [[Suite : Issues: Profile Locked]]
  • Layout issues or other things should use Gecko as the application name. As noted above, when an article applies to more than one application in a way that it would be wasteful to split up the articles because they would be practically identical, it may be best to dispose of the categories and just have the plain article title.

Editing Courtesy

  • Any time you edit a page, please add a short comment in the "Summary" field about the change you made. This makes it easier for others to see what has changed. Importantly, it can help make it easier for us to distinguish knowledge base spamming/vandalism from legitimate contributions.
  • If you find yourself wanting to change an entry back to an earlier revision, ask yourself if the current version had a useful purpose, and whether it really is necessary to change it back.
  • Document reasons for potentially controversial changes on the Talk pages.
  • Accept changes to your entries in a spirit of helpfulness.
  • If someone consistently makes certain types of mistakes or formatting quirks, consider placing a message in their User page.

Superfluous Information

  • In knowledge base articles, do not insert signatures, links to sites that are not related to Mozilla products, or other superfluous information. If you want to give a link to your own personal website, for example, then put it in your User page, not in the article. In short, if the information or link is not directly related to the topic of the article, then don't include it in the article.
  • Of course, signatures are welcome (even helpful) in the Talk pages, so do not hetitate to use them there.

Test Editing Pages

  • A sandbox for showing off the wiki's features.
  • Another test page - Now with extra markup tests!
  • If you want to do some silly tests using a page use this page.