Introduction
Disambiguation in the MDC wiki is the process of resolving ambiguity, referring to the conflicts that occur when articles about two or more different topics have the same "natural" title.
Every page within the wiki must have a unique title. This can cause problems when there are two pages that could, theoretically, have the same title. For example, indexOf is a method for both the String and Array objects in JavaScript.
Like Wikipedia, we differentiate between pages by placing qualifiers in parentheses after the main title (i.e., "Mercury (planet)"). However, users looking for information on "indexOf" will likely come to Devmo and type "indexOf" into the search box. The search will return results for all pages that contain "indexOf", which could eventually become somewhat unwieldy, given that it will show up in titles, articles, tutorials, code samples, and references throughout the wiki. In order to help readers find what they're looking for more easily, we have started to add disambiguation pages to the wiki.
When to create a disambiguation page
Disambiguation pages should be created only to resolve ambiguity between two or more pages.
How to create a disambiguation page
Disambiguation pages are hand-crafted by our editors to link to all of the various pages that a reader may be looking for when they search for an ambiguous term. These allow readers to quickly scan the list of ambiguous pages and choose the one they actually want.
To create a disambiguation page, simply create a page whose title is the ambiguous term; for example, indexOf.
What to include in a disambiguation page
When first creating a disambiguation page, you need to do two things:
Short introductory line
Add a short introductory line to the top of the page, such as "indexOf is a Method of various JavaScript objects:", "indexOf is used in various ways:", or, most simply, "indexOf can mean many things:".
The "disambig" template
Add the disambig template at the bottom of the page. This inserts a standard note and the Disambiguation category.
Linked list of ambiguous page titles
Then simply add a linked list of the ambiguous page titles, with a short summary for each. I'll refer you to the indexOf disambiguation page for examples.
If a list of linked titles and summaries becomes unwieldy, you are welcome to organize the list by dividing it up into logical sections or groupings.
Best Practices
- Disambiguation pages should only link to pages that currently exist within the wiki.
- Do not link to other pages in the summaries in a disambiguation page. For example, do not do this: "indexOf - method for the String object in JavaScript". Just leave it as "indexOf - method for the String object in JavaScript". Extraneous links serve no purpose on a disambiguation page.
- Shorten the link title, if necessary, to the term being disambiguated. Rather than linking to Core JavaScript 1.5 Reference:Objects:String:indexOf, use the alt-text facility to shorten it to indexOf.
- Disambiguation pages are not intended for games of "free association". Please use them carefully and only when needed.
Fixing links to disambiguated topics
After you create a disambiguation page, click the "What links here" link to see if any existing page links to your new disambiguation page. If so, please go to those pages and change the links where possible, so they point at the correct page within the wiki.
For example, if a page talking about the JavaScript String object's indexOf method links to the indexOf disambiguation page, that link should be changed so it points directly at the Core JavaScript 1.5 Reference:Objects:String:indexOf page.
If you are creating a disambiguation page that will involve moving an existing page, click on "What links here" to find all the pages that link to the page you are about to move. Make sure those pages are fixed or that they won't be adversely affected before you do the move.
A code of honor for creating disambiguation pages is to fix all of the links involved.
If you need help or have questions
If you're not sure how to name or disambiguate a page, please email Eric Shepherd or ask on the devmo-general mailing list.
Alternately, pop into IRC on the irc.mozilla.org server and ask someone in the #devmo channel.
For more information
The Wikipedia Disambiguation page outlines their policies and approaches. Note that our policies do not match precisely.