MozillaZine

User:Filipp0s/KB Introduction

From MozillaZine Knowledge Base

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/


Contents

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.