User:Filipp0s/KB Introduction: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
mNo edit summary
Line 1: Line 1:
==Getting Started==
Don’t feel daunted by the rules below; although it helps if you follow them, there will always be other editors willing to tidy your contributions if you don’t have the time to read all the guidelines in the links below. The important thing is getting your contributions here in the first place!
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 [http://en.wikipedia.org/wiki/Wiki wiki]; you are free to modify existing articles, and to create brand new ones.  


To begin editing, you need to [[Special:Userlogin|create a new account]].
'''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 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 blah blah


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.
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.  


Need more help? Ask blah blah


==General Guidelines==
==General Guidelines==
Line 99: Line 94:
* Each page also has a "History" link, which you can use to view that page's history of edits.
* 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.
* The [[Knowledge Base changes]] page is used to propose and discuss new ideas for and major changes to the Knowledge Base.
===Need help getting started?===
 
* If you're thinking of adding some information to a Knowledge Base article but aren't sure if it belongs there, feel free to use the article's "Talk" page to insert a comment or ask for feedback. To edit the Talk page of an article you're viewing, click on the "Discussion" link on the right and then on the "Edit this page" link.
* 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.



Revision as of 00:31, 1 April 2006

This Knowledge Base is a wiki; you are free to modify existing articles, and to create brand new ones.

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 blah blah

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.


General Guidelines

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.

Naming Conventions

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.

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: [[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]]

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

  • 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.
  • 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").
  • 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 <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.).

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 titles.
  • Use ==See also== when linking to articles on the KB. Use ==External links== to link to web pages outside of the Knowledge Base.
  • Use the dash and hyphen correctly [1] [2]. When using dashes and hyphens, you should not include white space around them. For example, use “9–16” and “Firefox—and Mozilla—can be used” which are achieved using “9&ndash;16” and “Firefox&mdash;and”.
  • "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 categories when editing or creating articles. categorize new articles


Knowledge Base maintenance

Varfix

Remember to sign and date your comments. Typing "~~~~" will do this automatically.

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.

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.

"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.