User:Filipp0s/KB Introduction: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
mNo edit summary
 
Line 1: Line 1:
This Knowledge Base is a [http://en.wikipedia.org/wiki/Wiki wiki]; you are free to modify existing articles, and to create brand new ones.  
This Knowledge Base is a wiki; you are free to modify existing articles, and to create brand new ones. Don&rsquo;t feel daunted by the rules below; <b><font color="#CC0000">the important thing is getting your contributions here in the first place!</font></b>  Other editors will tidy your contributions if you don&rsquo;t have the time to read the guidelines below.  
 
* '''To begin editing''', you need to [[Special:Userlogin|create a new account]]. To edit a page, click the "Edit this page" link at the right column the page.  
'''To begin editing''', you need to [[Special:Userlogin|create a new account]]. To edit a page, click the "Edit this page" link at the right column the page.
* '''To learn how to format a wiki page''' read our [[MozillaZine Knowledge Base:Formatting | formatting guide]]. To experiment use our [[Sandbox]]. You can do whatever you want there.  
 
* Need more help? Ask /article discussion/forumlink/
'''To learn how to format a wiki page''' read our [[MozillaZine Knowledge Base:Formatting | formatting guide]]. To experiment use our [[Sandbox]]. You can do whatever you want there. Need more help? Ask blah blah
 
Don&rsquo;t feel daunted by the rules below; <b><font color="red">the important thing is getting your contributions here in the first place!</font></b>  Other editors will tidy your contributions if you don&rsquo;t have the time to read the guidelines below.




==General Guidelines==
==General Guidelines==
* Accept changes to your entries in a spirit of helpfulness; experienced editors will often make changes to ensure that an article conforms to the rules. Of course, discussion relating to the changes is welcome on the corresponding Talk pages.
* Remember to sign and date your comments. Typing "<nowiki>~~~~</nowiki>" will do this automatically.
===Articles that apply to more than one application===
===Articles that apply to more than one application===
* If the article applies to both the Mozilla Suite and Firefox/Thunderbird, create it and edit it for Mozilla Suite and Firefox/Thunderbird, if you can. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla Suite too. This is a shame, because Mozilla Suite is in need of more people creating resources for it and converting old content to it.
* If the article applies to both the Mozilla Suite and Firefox/Thunderbird, create it and edit it for Mozilla Suite and Firefox/Thunderbird, if you can. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla Suite too. This is a shame, because Mozilla Suite is in need of more people creating resources for it and converting old content to it.
Line 14: Line 13:
* If you're creating a new article and you're not sure if it applies to more than one application (e.g., you're writing a Firefox article but you're not an experienced Mozilla Suite user), go ahead and write it for just one product. Someone else can edit it later if needed.
* If you're creating a new article and you're not sure if it applies to more than one application (e.g., you're writing a Firefox article but you're not an experienced Mozilla Suite user), go ahead and write it for just one product. Someone else can edit it later if needed.


==Creating Articles==
==Naming Conventions==
==Naming Conventions==
===Use short titles, with key words at the beginning===
* Good: <nowiki>[[Send page or link (Mozilla Suite)]]</nowiki>
* Bad: <nowiki>[[Use Send Page or Send Link to tell your friends about a great webpage (Mozilla Suite)]]</nowiki>
Try to avoid putting a word like "using" or "changing" at the beginning of the title when title will work fine without it. This will help as we move to categories, in which articles will be sorted alphabetically by title.
* OK: <nowiki>[[Using keyword searches]]</nowiki>
* Better: <nowiki>[[Keyword searches]]</nowiki>
===Specifying the application===
===Specifying the application===
For some articles, you should specify the application to which the article applies by putting "Firefox", "Thunderbird", or "Mozilla Suite" in parentheses at the end of the name of the article. Please do this '''only if''' the article applies exlusively to one application and needs to be distinguished from similarly titled articles for other applications (see examples below). Do '''not''' include the application name if the article applies to two or more applications, or if the article is about a feature that exists in only one application. If you are not sure if the application name should be included in the title, just leave it out and someone else can add it later if necessary.
For some articles, you should specify the application to which the article applies by putting "Firefox", "Thunderbird", or "Mozilla Suite" in parentheses at the end of the name of the article. Please do this '''only if''' the article applies exlusively to one application and needs to be distinguished from similarly titled articles for other applications (see examples below). Do '''not''' include the application name if the article applies to two or more applications, or if the article is about a feature that exists in only one application. If you are not sure if the application name should be included in the title, just leave it out and someone else can add it later if necessary.
Line 37: Line 44:
* Bad: <nowiki>[[Profile locked (Suite)]]</nowiki>
* Bad: <nowiki>[[Profile locked (Suite)]]</nowiki>
Layout issues or other things should use Gecko as the application name.
Layout issues or other things should use Gecko as the application name.
===Use short titles, with key words at the beginning===
When possible, use short page titles. 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.
* Good: <nowiki>[[Send page or link (Mozilla Suite)]]</nowiki>
* Bad: <nowiki>[[Use Send Page or Send Link to tell your friends about a great webpage (Mozilla Suite)]]</nowiki>
Try to avoid putting a word like "using" or "changing" at the beginning of the title when title will work fine without it. This will help as we move to categories, in which articles will be sorted alphabetically by title.
* OK: <nowiki>[[Using keyword searches]]</nowiki>
* Better: <nowiki>[[Keyword searches]]</nowiki>


===Capitalization===
===Capitalization===
Line 55: Line 54:


==Style guide==
==Style guide==
* Accept changes to your entries in a spirit of helpfulness; experienced editors will often make changes to ensure that an article conforms to the rules. Of course, discussion relating to the changes is welcome on the corresponding Talk pages.


* Don't overdo linking. Since links stand out visually, they can disrupt the reader's flow and become a distraction. Try not to put the same link more than once in a single logical unit of an article (e.g., a section of a tutorial).
* "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup.
* Don't capitalize entire words.
* Avoid superfluous information.  
* Avoid superfluous information.  


===Special punctuation and formatting===
===Special punctuation and formatting===
* '''Menu sequences''': Use "arrows" to denote menu order (e.g. "Tools -> Options"), and place a space either side of the arrow to facilitate line breaks. Use quotation marks around the whole menu sequence. In cases where menu sequences differ by OS, it may be helpful to include a link to [[Menu differences in Windows, Linux, and Mac]] within the menu sequence itself (e.g., "[[Menu differences in Windows, Linux, and Mac|Tools -> Options]] -> Advanced").
* '''Menu sequences''': Use "arrows" to denote menu order (e.g. "Tools -> Options"), and place a space either side of the arrow to facilitate line breaks. Use quotation marks around the whole menu sequence. In cases where menu sequences differ by OS, it may be helpful to include a link to [[Menu differences in Windows, Linux, and Mac]] within the menu sequence itself (e.g., "[[Menu differences in Windows, Linux, and Mac|Tools -> Options]] -> Advanced").
* '''Keyboard and mouse actions''': left-click, right-click etc. are hyphenated and uncapitalized; Shift, Ctrl, Alt etc. have their first letter capitalized (and only their first letter); key combinations are written using "+" so that "hold down Ctrl and press 'D'" should be written "Ctrl+D".
* '''Keyboard shortcuts''': Put quotation marks around keyboard shortcuts (e.g., "Ctrl+PageDown")
* '''Path names''': Enclose these in <nowiki><tt></nowiki> tags so that they will appear in a monospace font (e.g., <tt>C:\Program Files\Mozilla Firefox\firefox.exe</tt>). Folders whose location varies (e.g., "profile folder" and "installation directory") can be enclosed in angle brackets when part of a path (e.g., <tt><profile folder>/chrome/overlayinfo/</tt>).
* '''Path names''': Enclose these in <nowiki><tt></nowiki> tags so that they will appear in a monospace font (e.g., <tt>C:\Program Files\Mozilla Firefox\firefox.exe</tt>). Folders whose location varies (e.g., "profile folder" and "installation directory") can be enclosed in angle brackets when part of a path (e.g., <tt><profile folder>/chrome/overlayinfo/</tt>).
* '''Directory & file names''': In general, put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <nowiki><tt></nowiki> instead).
* '''Directory & file names''': In general, put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <nowiki><tt></nowiki> instead).
* '''Mail folders''' (as listed in the folders pane): Write these as simply Inbox, Sent, Junk, Trash, etc., without italics or quotation marks; the corresponding files for each should be treated like other file names and normally be written in quotation marks (e.g., "Inbox", "Sent", "Junk", "Trash", etc.).
* '''Mail folders''' (as listed in the folders pane): Write these as simply Inbox, Sent, Junk, Trash, etc., without italics or quotation marks; the corresponding files for each should be treated like other file names and normally be written in quotation marks (e.g., "Inbox", "Sent", "Junk", "Trash", etc.).
===Other style considerations===
* Don't start too many small, idiosyncratic paragraphs. If several paragraphs each consist of a couple of sentences with only a few lines length, try to combine them into a single paragraph.
* Use bolding and italics only when absolutely necessary.
* Don't overdo linking. Since links stand out visually, they can disrupt the reader's flow and become a distraction rather than an aid. Try not to put the same link more than once in a single logical unit of an article (e.g., a section of a tutorial). For example, if you mention "profile folder" several times, link only the first one, or the one that's relating to something technical, at a point where the reader might logically want to read up on the specifics.
* Headers/subheaders within articles should be capitalized in the same way as [[Article naming conventions|article titles]].
* Use <nowiki>==See also==</nowiki> when linking to articles on the KB. Use <nowiki>==External links==</nowiki> to link to web pages outside of the Knowledge Base.
* Use the dash and hyphen correctly [http://en.wikipedia.org/wiki/Dash] [http://en.wikipedia.org/wiki/Hyphen]. When using dashes and hyphens, you should not include white space around them. For example, use &ldquo;9&ndash;16&rdquo; and &ldquo;Firefox&mdash;and Mozilla&mdash;can be used&rdquo; which are achieved using &ldquo;9&amp;ndash;16&rdquo; and &ldquo;Firefox&amp;mdash;and&rdquo;.
* "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup.
* Don't capitalize entire words.


==Categorizing==
To allow people to find information more easily, it is helpful to use [[Rules/Categories | categories]] when editing or creating articles.
[[Rules/Categories | categorize new articles]]




Line 87: Line 74:
* [[:Category:Articles_to_update|Articles to update]]
* [[:Category:Articles_to_update|Articles to update]]
* [[Special:Whatlinkshere/Template:Stub|Stubs]] -- articles to expand
* [[Special:Whatlinkshere/Template:Stub|Stubs]] -- articles to expand
===Categorizing===
To allow people to find information more easily, it is helpful to use [[Rules/Categories | categories]] when editing or creating articles.
[[Rules/Categories | categorize new articles]]
===Templates===
There are numerous templates available to insert standardized content and/or formatting into pages. For instance, if you come across an article  that needs a formatting makeover in order to follow the style guidelines listed on this page, you can insert <nowiki>{{cleanup}}</nowiki> at the top of the article. This will expand to the message shown [[Template:Cleanup | here]].
For a list of useful templates and further explanation, see [[Rules/Templates]].


==Varfix==
==Varfix==
Remember to sign and date your comments. Typing "<nowiki>~~~~</nowiki>" will do this automatically.
===Keeping up with changes===
===Keeping up with changes===
* The [[Special:Recentchanges|Recent changes]] page, linked on the right, is an automatically generated list of the most recent edits to the Knowledge Base.
* The [[Special:Recentchanges|Recent changes]] page, linked on the right, is an automatically generated list of the most recent edits to the Knowledge Base.
Line 98: Line 93:


* If you're having trouble with editing-related tasks&mdash;for example, you can't figure out how to create a new page&mdash;feel free to ask for assistance on the [[Help wanted]] page.
* If you're having trouble with editing-related tasks&mdash;for example, you can't figure out how to create a new page&mdash;feel free to ask for assistance on the [[Help wanted]] page.
===Templates===
There are numerous templates available to insert standardized content and/or formatting into pages. For instance, if you come across an article  that needs a formatting makeover in order to follow the style guidelines listed on this page, you can insert <nowiki>{{cleanup}}</nowiki> at the top of the article. This will expand to the message shown [[Template:Cleanup | here]].
For a list of useful templates and further explanation, see [[Rules/Templates]].
==="Post a comment" feature===
For editing a talk page, one can optionally use the "Post a comment" feature, but only for a new thread and for a reply to be put at the bottom of the last thread. To post a comment in this way, click on the "+" link in the sidebar.
---------------------------------------------------------------------

Latest revision as of 04:06, 1 April 2006

This Knowledge Base is a wiki; you are free to modify existing articles, and to create brand new ones. Don’t feel daunted by the rules below; the important thing is getting your contributions here in the first place! Other editors will tidy your contributions if you don’t have the time to read the guidelines below.

  • To begin editing, you need to create a new account. To edit a page, click the "Edit this page" link at the right column the page.
  • To learn how to format a wiki page read our formatting guide. To experiment use our Sandbox. You can do whatever you want there.
  • Need more help? Ask /article discussion/forumlink/


General Guidelines

  • Accept changes to your entries in a spirit of helpfulness; experienced editors will often make changes to ensure that an article conforms to the rules. Of course, discussion relating to the changes is welcome on the corresponding Talk pages.
  • Remember to sign and date your comments. Typing "~~~~" will do this automatically.

Articles that apply to more than one application

  • If the article applies to both the Mozilla Suite and Firefox/Thunderbird, create it and edit it for Mozilla Suite and Firefox/Thunderbird, if you can. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla Suite too. This is a shame, because Mozilla Suite is in need of more people creating resources for it and converting old content to it.
  • Not every article that could be written to cover both the Mozilla Suite and Firefox/Thunderbird should be written this way. In some cases it might make the article excessively messy, especially if it refers to a series of steps or menu choices that differ in the Mozilla Suite and Firefox/Thunderbird (example). In such cases it's probably best not to write combined product articles. Use your best judgment.
  • If you're creating a new article and you're not sure if it applies to more than one application (e.g., you're writing a Firefox article but you're not an experienced Mozilla Suite user), go ahead and write it for just one product. Someone else can edit it later if needed.

Creating Articles

Naming Conventions

Use short titles, with key words at the beginning

  • Good: [[Send page or link (Mozilla Suite)]]
  • Bad: [[Use Send Page or Send Link to tell your friends about a great webpage (Mozilla Suite)]]

Try to avoid putting a word like "using" or "changing" at the beginning of the title when title will work fine without it. This will help as we move to categories, in which articles will be sorted alphabetically by title.

  • OK: [[Using keyword searches]]
  • Better: [[Keyword searches]]

Specifying the application

For some articles, you should specify the application to which the article applies by putting "Firefox", "Thunderbird", or "Mozilla Suite" in parentheses at the end of the name of the article. Please do this only if the article applies exlusively to one application and needs to be distinguished from similarly titled articles for other applications (see examples below). Do not include the application name if the article applies to two or more applications, or if the article is about a feature that exists in only one application. If you are not sure if the application name should be included in the title, just leave it out and someone else can add it later if necessary.

Examples where the application name is included in the article title:

Examples where the application name is not included in the article title:

Note: this is a change from the old naming convention, in which article titles indicated whether articles were "FAQs", "Tips", or "Issues" (e.g., Thunderbird : FAQs : Global Inbox). Many of the existing articles were created under the old naming system and have not yet been renamed. Please do not follow this old naming system when creating new articles.

Application names

Application name links should only use the application name, such as "Firefox", "Thunderbird", "Nvu", "Sunbird", or "Camino" and not "Mozilla Firefox", "Mozilla Thunderbird" or "Linspire Nvu". The exception is the Mozilla Suite, which should be linked to and called "Mozilla Suite", not "Mozilla", "Suite", "Seamonkey", or any other name.

  • Bad: [[Bookmarks (Mozilla Firefox)]]
  • Bad: [[Profile locked (Suite)]]

Layout issues or other things should use Gecko as the application name.

Capitalization

Do not capitalize The First Letter of Each Main Word in the Title.

  • Good: [[Importing and exporting your mail]]
  • Bad: [[Importing and Exporting Your Mail]]

Exception: terms such as Search Bar and Junk Mail Controls, which refer to named product features and function as proper nouns, should be capitalized in article titles. See In-house style for a list of common terms to be capitalized.


Style guide

  • Don't overdo linking. Since links stand out visually, they can disrupt the reader's flow and become a distraction. Try not to put the same link more than once in a single logical unit of an article (e.g., a section of a tutorial).
  • "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup.
  • Don't capitalize entire words.
  • Avoid superfluous information.

Special punctuation and formatting

  • Menu sequences: Use "arrows" to denote menu order (e.g. "Tools -> Options"), and place a space either side of the arrow to facilitate line breaks. Use quotation marks around the whole menu sequence. In cases where menu sequences differ by OS, it may be helpful to include a link to Menu differences in Windows, Linux, and Mac within the menu sequence itself (e.g., "Tools -> Options -> Advanced").
  • Path names: Enclose these in <tt> tags so that they will appear in a monospace font (e.g., C:\Program Files\Mozilla Firefox\firefox.exe). Folders whose location varies (e.g., "profile folder" and "installation directory") can be enclosed in angle brackets when part of a path (e.g., <profile folder>/chrome/overlayinfo/).
  • Directory & file names: In general, put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <tt> instead).
  • Mail folders (as listed in the folders pane): Write these as simply Inbox, Sent, Junk, Trash, etc., without italics or quotation marks; the corresponding files for each should be treated like other file names and normally be written in quotation marks (e.g., "Inbox", "Sent", "Junk", "Trash", etc.).


Knowledge Base maintenance

Categorizing

To allow people to find information more easily, it is helpful to use categories when editing or creating articles. categorize new articles

Templates

There are numerous templates available to insert standardized content and/or formatting into pages. For instance, if you come across an article that needs a formatting makeover in order to follow the style guidelines listed on this page, you can insert {{cleanup}} at the top of the article. This will expand to the message shown here.

For a list of useful templates and further explanation, see Rules/Templates.


Varfix

Keeping up with changes

  • The Recent changes page, linked on the right, is an automatically generated list of the most recent edits to the Knowledge Base.
  • When you're logged in, clicking on the "Watch" link on a page will add that page to your watchlist. All your watched pages will appear in bold in the Recent changes list.
  • Each page also has a "History" link, which you can use to view that page's history of edits.
  • The Knowledge Base changes page is used to propose and discuss new ideas for and major changes to the Knowledge Base.
  • If you're having trouble with editing-related tasks—for example, you can't figure out how to create a new page—feel free to ask for assistance on the Help wanted page.