Joomla! Documentation™

Disambiguation in the Joomla! Documentation wiki is the process of resolving conflicts in article titles that occur when a single term can be associated with more than one topic, making that term likely to be the natural choice of title for more than one article. In other words, disambiguations are paths leading to the different article pages that could use essentially the same term as their title.

For example, the word "Mercury" can refer to several different things, including: an element, a planet, an automobile brand, a record label, a NASA manned-spaceflight project, a plant, and a Roman god. Since only one page can have the generic name "Mercury", unambiguous article titles must be used for each of these topics: (e.g. at Wikipedia) Mercury (element), Mercury (planet), Mercury (automobile), Mercury Records, Project Mercury, Mercury (plant), Mercury (mythology). There must then be a way to direct the reader to the correct specific article when an ambiguous term is referenced by linking, browsing or searching; this is what is known as disambiguation.

Two different methods of disambiguating are discussed here:

• disambiguation links — at the top of an article, a note that links the reader to articles with similar titles or concepts that the reader may have been seeking instead of the article in which the links appear.
• disambiguation pages — non-article pages that contain no content and only refer users to other documentation pages.

Deciding to disambiguate

Ask yourself: When a reader enters a given term in the search box and pushes "Go", what article would they most likely be expecting to view as a result? For example, when someone looks up "Language", would they expect to find information on localised extensions? On a language pack? On how to translate Joomla? On installing a Language using the Language Manager in the Back-end? On the Language package of the Joomla! 1.5 Framework? When there is risk of confusion, the page for an ambiguous term should have a way to take the reader to any of the reasonable possibilities for that term; either the top of the page should have one or more disambiguation links, or the page itself should be a disambiguation page.

Disambiguation links

Users searching for what turns out to be an ambiguous term may not reach the article they expected. Therefore, any article with an ambiguous title should contain helpful links to alternative articles placed at the top of the article by using one of the templates shown below. Their parameters are described in Template:Otheruses4/doc and illustrated at Project:Otheruses templates (example usage).

Usage guidelines

• Do not pipe disambiguation links. Showing the entire linked article title avoids confusion, which is the reason for the link in the first place.
• As noted above, disambiguation links should be placed at the top of an article. Bottom links are deprecated, since they are harder to find and easily missed. For alternatives that are related to the article but not a source of ambiguity, the "See also" section is more appropriate.
• While there is no specific prohibition against it, adding disambiguation links to a page with a name that clearly distinguishes itself from the generic term is discouraged. For example, Application (Package) is clearly about one specific package and not about any of the many other meanings of "Application". It is very unlikely that someone arriving there would have been looking for any other "Application", so it is unnecessary to add a link pointing to the Application disambiguation page. However, it would be perfectly appropriate to add a link to Framework:Application -- but not, say, Administrator (Application) -- to its "See also" section.
• See Project:Hatnotes for other guidelines on improper disambiguation links.

Disambiguation pages

Each of these pages comprises a list (or multiple lists, for multiple senses of the term in question) of similarly-titled links.

• Link to the primary topic (if there is one):

A Package is a group of related PHP classes.

• Start each list with a short introductory sentence fragment with the title in bold, and ending with a colon. For example:

Package may refer to:

• Try to start each entry in the list with a link to the target page.
• Each bulleted entry should, in almost every case, have exactly one navigable (blue) link; including more than one link can confuse the reader.
• Do not pipe the name of the links to the articles being listed.
• Only include related subject articles if the term in question is actually described on the target article.

Include the template {{disambig}} at the bottom as an indicator of the page's status. Following the template, include any of the standard categories as appropriate.

For a prime example of an actual disambiguation page, see Application.

What not to include

Duplicate topics

Disambiguation should not be confused with merging duplicate articles (articles with different titles, but regarding the very same topic, for example "Administrator" and "Back-end". These are handled with redirects.

Partial title matches

Do not add links that merely contain part of the page title (where there is no significant risk of confusion). Only add links to articles that could use essentially the same title as the disambiguated term. Disambiguation pages are not search indices nor are they glossaries.

Famous exception

Due to the naming schema of the Joomla! Framework whereas each PHP class is prefixed with the capital letter "J", the base name of those classes are considered perfect candidates to appear on a disambiguation page, i.e. JApplication ~ Application -- despite this is a partial title match. This is not an invitation to include every class found in such a package, that's what package pages are for, e.g. Whatever (Package) for the narrative documentation, and Framework:Whatever for the API facts.

Summary or multi-stub pages

Several small topics of just a paragraph or so each can co-exist on a single page, separated by headings. Although this is similar to a disambiguation page, the disambiguation notice should not be put here, as the page doesn't link to other articles closely associated with a specific term.

As each section grows, there may come a time when a subject should have a page of its own.

Although many pages rely on this principle, it has become more common for each subject to have a separate page for its own stub. Many compiled from "chunks" to achieve Modular Documentation.

Always use {{split}} or {{splitsection}}, and reach consensus before attempting the split. Wikipedia's motto, "Be bold in updating pages" doesn't apply, as it is very difficult to revert a split, often requiring extensive assistance by administrators.

(to be continued --CirTap 14:55, 18 February 2008 (EST))