Rules and guidelines

From MozillaZine Knowledge Base
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Welcome, new and existing editors! Your contributions of Mozilla-related knowledge are most welcome, and you don't need to be an “expert” to help out. In particular, if you have come to the Knowledge Base from the forums after having a question answered or a problem solved, you are encouraged to write up anything that you learnt there, even if you didn’t fully understand why the solution works.

The main rules are:

  • Don't create an edit war. Nobody "owns" an article, you're collaborating with other editors. That can take some getting used to. Use the discussion page for the article to discuss any issues. If necessary, use the other editor's Talk page or send them a private message if they have an account on the Mozillazine forums.
  • Use the Knowledge Base changes article to propose/discuss changes that effect other editors such as creating a new category or changing the way profiles are documented for multiple applications. Its also a useful place to ask for advice.
  • Don't publicly share your username/password (it creates "de facto" anonymous user editing).
  • The mozillaZine forum rules regarding no offensive language, spam, advertising or adult content, etc. also apply to the Knowledge Base, including user pages.
  • Use common sense.

Don’t feel daunted by the sections below; although it helps if you follow them, there will always be other editors willing to tidy up 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! Of course, if you’re planning on becoming a regular contributor then you should try to follow the rules and guidelines more closely.

Get some editing practice

Use the sandbox to play around with the wiki system.

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 vandalism from legitimate contributions.
  • Document reasons for potentially controversial changes on the Talk pages.
  • Accept changes to your entries in a spirit of helpfulness; experienced editors will often make changes to ensure that an article conforms to the guidelines. Of course, discussion relating to the changes is welcome on the corresponding Talk pages.
  • 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 someone consistently makes certain types of mistakes or formatting quirks, consider placing a message in their User Talk page.

Avoid superfluous information

  • In Knowledge Base articles, please 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 and helpful in the Talk pages, so please do use them there.

Creating new articles

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 articles. You don't want to waste your time by adding information that already exists. Please read and follow the article naming conventions when creating new articles or moving existent ones. You don't have to read that if you only edit existing pages.

The knowledge base is a wiki. It doesn't support HTML or bbcode, it has its own markup language. If you're not used to wiki markup the formatting article is a useful primer.

To actually create the new article, visit the Sandbox and create a link to your proposed article, such as [[My new article]]. Preview the Sandbox page, and then click on the link. This will take you to the (currently empty) page for your article, where you can add your content.

Style guidelines

Please have a look at In-house style. We're trying to give the Knowledge Base a uniform look, and you can help by following these guidelines as much as possible.

Categorizing articles

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

Article content

Articles that apply to more than one application

  • If the article applies to both Mozilla Suite/SeaMonkey and Firefox or Thunderbird, create it and edit it to include SeaMonkey also, if you can. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to SeaMonkey. This is a shame, because SeaMonkey 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 SeaMonkey and Firefox or 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 SeaMonkey and Firefox or 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 SeaMonkey user), go ahead and write it for just one product. Someone else can edit it later if needed.

Removing obsolete information

Information about obsolete versions (i.e, versions that are no longer supported and which haven't been updated in over a year) may be removed if it is long, confusing, or distracting if the corresponding information about current versions is present. However, a comment such as "Applies to Firefox since release 0.9" in articles about preferences is a good example of information that shouldn't be removed. It's very short, and the historical perspective can be useful.

Keep in mind that older operating systems (e.g., Windows 98/Me and Mac OS X 10.3) do not meet the requirements for current Mozilla applications and some outdated versions (e.g., SeaMonkey 1, Firefox 2 and Thunderbird 2) may still be popular for various reasons. Use common sense before removing information that may still be useful.

Quality

If you see a problem with an article you are encouraged to either fix the problem or add a comment in the article's discussion page. Nobody owns an article, they're collaborative efforts. The Request for comment, cleanup, update, and stub templates are meant to identify articles whose quality could be improved and to try to focus attention and resources on the article. The main difference is that the Request for comments template is used to request a review of an article when it's not clear what should be done.

If you go to Category:Articles_to_clean_up, Category:Articles_to_update, Category:Stub, and/or Category:Request_for_comments and click on Watch you'll be notified of any changes to that category. Each of those templates adds some text in a box to the article and adds it to one of those four categories.

Technical information

These guidelines apply to support/issues articles (directing people how to fix a problem) and how-to articles that support articles use (such as Profile folder).

The MozillaZine Knowledge Base is intended to be used by both novice and advanced users. Because of that, here's a few things to keep in mind:

Articles should be written appropriately for the audience. This means that an article for a situation that could happen to a novice user or an article that describes steps that a novice user might want to take should be written at the level of a novice user. For example, a novice user will not likely know how to "set extensions.checkCompatibility to false" without us providing step-by-step instructions, whether directly in the article or via a link to another article. Conversely, articles that are written for situations that would only happen to more advanced users can assume that these users would know how to set preferences and do other somewhat advanced things.

In an article intended to be understood by novice users, if the only way to perform a task is technically involved, it should be marked as "Technical" or "Advanced" in the section header.

Keep technical explanations in articles intended for novice users to a minimum. If you feel it should be included, put it in a section called "Technical overview" or similar.

Helping users find the correct article

When similar articles exist and users might reasonably choose the incorrect article, provide links to the other articles in the introduction and contrast the current article to the other articles.

Add-on links

As a general rule, link to addons.mozilla.org (AMO) whenever possible instead of linking to the author's website or elsewhere, unless you have a good reason to use an alternate link.

Dispute resolution

Use the Knowledge Base changes page to announce new suggestions for changes that might affect other editors, such as creating a new category.

There is an unapproved working draft of a dispute resolution process. The main reason why there has been no attempt to formally approve a dispute resolution process is (so far) we've managed to avoid any editing wars. Most disputes are resolved using the article's discussion page. If you have a deadlock (and it's not over something inconsequential or petty) you can formally request comments using the Request for comments template. That might help you develop a consensus or provide the outside perspective needed to resolve the dispute.

Talking to authority