Editing Help:Index pages

{{Archived notice}}

An [[Wikipedia:index|index]] is a system to make finding information easier. An '''index page''' on a [[Wikipedia:wiki|wiki]] is a page that mimics a [[Wikipedia:Index (publishing)|back-of-the book style index]] in traditional publishing. However, an index page on a wiki may cover any arbitrary collection of content, which may be larger or smaller than the entire wiki on which the index page resides. A single wiki may have more than one index page to cover different subject areas. In addition, index pages typically list page links in alphabetical order, as compared to list and outline pages, that typically list page links by topic.

== In general ==

An index page on {{SITENAME}} is an example of [[Wikipedia:Web indexing|Web indexing]].

A well-developed index page provides a comprehensive and structured<ref name="Leise2002">{{Cite web|url=http://web.archive.org/web/20121116005821/http://boxesandarrows.com/view/improving_usability_with_a_website_index|title=Improving Usability with a Website Index|accessdate=2010-12-28|first=Fred|last=Leise|date=2002-07-15}}</ref> list of links to pages relating to a particular topic area on {{SITENAME}}. See the [[#Comparison with other navigation aids|comparison with other navigation aids]] section below to understand the differences between index pages and other on-wiki methods of summarizing the available content for a topic area. Index pages can exist alongside the other tools for summarizing and navigating content. See the [[#Comparison with automatic indexing|comparison with automatic indexing]] to learn how on-wiki indexing differs from indexing in book-oriented publishing systems such as [[Wikipedia:DocBook|DocBook]].

An on-wiki index page is directly editable. To add an entry to the index, you edit the index page itself. This is in contrast to:

* [[Wikipedia:Help:Category|Categories]] on a wiki - to add a link to a page on a category page, the human editor must add a category code to the linked-to page. The [[Wikipedia:MediaWiki|MediaWiki]] software reads the category codes throughout the wiki, and from them constructs the category pages.
* Book-oriented publishing systems such as DocBook, which require the human editor to add indexing codes throughout the document to mark locations for the index to refer to. In a document publishing step, software then compiles a list of all the indexing codes, determines their page numbers, and builds an index from them.

=== Content ===

An index page needs a clear definition of its content. That is, someone must clearly define what does and does not belong in each index, and whether the index links only to pages on {{SITENAME}}, or also to external sites. The index can have a [[Wikipedia:Wikipedia:Subpages|subpage]] with the title of "About" with notes about what content is appropriate.

=== Navigation ===

There are two main approaches for finding something in an index:

* You can use the index as you would a paper index, looking in the "U" section, for example, for "Uploading", and following [[Wikipedia:cross-reference|cross-reference]]s that look interesting.
* You can do a Ctrl+F or Command+F search in your [[Wikipedia:Web browser|Web browser]], looking for a particular word or phrase.

Every subject area, which might have an index page, has its own associated vocabulary. The important terms for the subject are likely to appear as alphabetized headings; when searching for such terms, the first approach may be better. For less common words, the second approach may be better: many times, a particular word (keyword) does not correspond to any alphabetized heading, but it does appear in the title of a page, in a subtopic within a major topic, or in the summary text that follows the link in an entry.

An index may not list every possible synonym for the term you have in mind, so if you don't find what you want on your first attempt, search for related terms. The particular words you initially think of to describe a concept may not exactly match the words other editors used to document it. Also, the first relevant link you find in an index may not tell the whole story on your topic of interest. You should repeat your Ctrl+F searches to be sure you find all instances of your search terms in the index. You may find related terms when you read the pages linked from the index, then return to the index to search for them as well.

The more familiar you become with an index, and with the vocabulary of its subject area, the more useful the index should become to you.

== Linking to a major topic within an index ==

When you are editing a page elsewhere on {{SITENAME}}, you may wish to link to a topic heading in this index. There are two types of topic headings: major and minor.

A major topic has multiple entries in the index. A minor topic says "''see'' X" or just points to a single wikilink (essentially, a topic that is only a single line in the index). You shouldn't link to a minor topic, there is no point in doing so, since you can just as easily link to whatever the minor topic links to.

Every major topic has one or more [[Wikipedia:Help:Link#Section linking (anchors)|anchors]], typically consisting of three to ten or so characters. This makes it easy to [[Commons:Commons:Talk page guidelines|post]] a wikilink like this:

<small>''To-do'': replace this example with one that works on {{SITENAME}}, after I build at least one index page here.</small>

* ''For information about copyright on Commons, see [[Commons:COM:EIC#Copyright]] in the Editor's index.''

The format of the wikilink in this example is:

 <nowiki>[[Commons:COM:EIC#Copyright]]</nowiki>

where "<code>#Copyright</code>" is an [[Wikipedia:Help:Link#Section linking (anchors)|anchor]] within the index.

Most major topics in the index, and some of the more important subtopics, visibly display their anchor names with the {{Tl|Shortcut}} template. This makes it easy to copy a shortcut such as [[Commons:COM:EIC#Upload]], and then paste it elsewhere on {{SITENAME}} (typically in the User:, Project: ({{SITENAME}}:), or Talk: [[Wikipedia:Help:Namespace|namespaces]]). For example, this saves time when answering questions or discussing subject matter that the index covers. For example, the [[Wikipedia:WP:EIW|Editor's index to Wikipedia]] links to pages that answer most questions about using Wikipedia that appear on the [[Wikipedia:WP:HD|Wikipedia Help desk]].

== Editing an index ==

As with any article or project page, evaluate any potential change you want to make to an index page. Because of the structured nature of an index, changes can have wider impact than on more narrative pages. For significant changes, consider posting your proposed change on the index page's [[Wikipedia:Help:Talk page|talk page]].

== Notes on the format of an index ==

=== Asterisks and spaces ===

The formatting convention in an index (''note the spaces, they're important'') is:
 * Topic:
 **<nowiki>[[Page name of entry 1]]</nowiki>
 ** Subtopic:
 ***<nowiki>[[Page name of entry 2]]</nowiki>

The space just before a topic or subtopic name is very useful when editing - it helps find one's place in the index. It's also useful when dumping the contents of the index into a word processor or spreadsheet, and then sorting. Such spaces are invisible to the reader.

=== Names and redirects ===

When the name of a page changes (that is, someone [[Wikipedia:WP:MOVE|moves a page]]), the index should also be changed. The intent of the index is to show the ''current'' name of pages, not just [[Wikipedia:WP:REDIRECT|redirect]] an editor to a correct page when clicking a wikilink. (The current name is important when searching with Ctrl+F, for example.)

The easiest way to find which pages have been renamed is the user script [[Wikipedia:User:Dschwen/highlightredirects.js]], which highlights (in green) redirects on a page, after the (added) tab on the page is clicked. Running this once per month or so is sufficient. (This also is helpful in identifying pages which have been merged, so that entries can be removed as appropriate.)

=== Anchors ===

[[#Linking to a major topic within an index|As mentioned above]], every major topic has an anchor, as a way to [[Wikipedia:Help:Link#Section linking (anchors)|jump to a specific place]] in an index. In edit mode, these anchors look like:
 <nowiki><span id="Copyright"/></nowiki>
or:
 <nowiki>{{Anchor|Copyright}}</nowiki>

If you add more anchors, try to keep them around six characters if possible. If an anchor contains multiple words, please separate them with underscores rather than spaces. If you add multiple anchors to the same major topic, the {{Tl|Anchor}} template simplifies the code:

 <nowiki><span id="Copyright"/><span id="Copyrig"/><span id="Copyr"/><span id="Copy"/></nowiki>
vs:
 <nowiki>{{Anchor|Copyright|Copyrig|Copyr|Copy}}</nowiki>

Anchors could have been the same as topic names, such as: <code><nowiki><span id="Naming an article"/></nowiki></code>. But that would have made anchors brittle: if the topic heading in this example were to change from "Naming an article" to "Naming of articles", all of the links to this anchor would break, and someone would have to find and fix them, or add an additional anchor. More importantly, it would require external (incoming) links to a major topic to spell the anchor exactly right; it's easier to just get the first six characters or so right.

Shorter anchors are also easier to remember. But anchors must also be distinct. Be especially careful when you add an anchor that doesn't begin with the same letter as the section you are editing. For example, if you are adding an anchor to the "D" section and the first letter of the anchor is "F", check the "F" section to make sure you are not duplicating an anchor already in use there. Obviously, to avoid duplications, it is best if anchor names start with the same letter as the section they are in.

You can search for an anchor name to see if it is already in use, by clicking the "edit" tab at the top of an index page to open the entire index page in an edit window, and searching in your browser with Ctrl+F or Command+F for the anchor name.

==== Visible anchors ====

You can use {{Tl|Shortcut compact}} to display a visible link for an anchor. This template is better than the {{Tl|Shortcut}} template, because:

* {{Tl|Shortcut compact}} takes up less vertical space, allowing its use on successive list items. For example, when several consecutive major topics have no intervening subtopics, you can still display shortcuts for them.
* {{Tl|Shortcut compact}} displays correctly even on sub-items in a list, whereas {{Tl|Shortcut}} does not. The latter template works best at the top of the whole page, or at the top of a section, but not in a wikitext list.
* The Wikipedia version of {{Tl|Shortcut}} automatically inserts anchors for its arguments. This is undesirable when the arguments themselves contain [[Wikipedia:fragment identifier|fragment identifier]]s. The problem is that the {{Tl|Shortcut}} template uses the entire shortcut name to act as the anchor name, but we only want the portion that appears after the [[Wikipedia:Number sign|number sign]] (#) to be the anchor. {{Tl|Shortcut compact}} avoids this problem by not attempting to automatically insert anchors.

<small>''To-do'': show an example after we build a first index page on {{SITENAME}} and have some wikitext to use as an example. </small>

=== Piped links ===

An index should not use [[Wikipedia:Help:Piped link|piped links]] for entries, because showing the full namespace prefix and page name adds value. In some cases, this requires somewhat duplicate text, to preserve the alphabetical order of the index. An example is:
 <nowiki>* Boldness: [[Commons:Don't be bold]] (essay)</nowiki>

An index may use piped links for internal navigation (as anchors, as mentioned above), and (rarely) as part of the explanatory text to the right of an entry in the index, but never as part of leftmost wikilink in an entry.

==== Interwiki links ====

<small>''To-do'': edit this section to make more sense on {{SITENAME}}.</small>

It is particularly important not to obscure [[Wikipedia:Help:Interwiki linking|interwiki links]] with piped links in index entries. When the index links to a page outside of {{SITENAME}}, the reader must be aware of this. Project pages on [[Wikipedia:Wikimedia Foundation|Wikimedia Foundation]] wikis (such as the [[Wikipedia:English Wikipedia|English Wikipedia]] may not strictly apply to {{SITENAME}}, but are useful as suggestions when {{SITENAME}} has no corresponding project page to cover a certain topic which nevertheless arises on {{SITENAME}}. The presence of an interwiki link prefix is necessary to caution the reader to use judgment when interpreting a guideline or policy from another wiki. For example:

 <nowiki>**[[Wikipedia:Wikipedia:Consensus]] ([[Wikipedia:WP:CON]]) (policy on Wikipedia; Commons appears to have no separate policy on consensus)</nowiki>

Ideally, the need for such interwiki links should decline as the {{SITENAME}} community codifies more of its policies, guidelines, and practices which it more or less inherited from other wikis. The sheer volume of such documentation makes this a slow process.

=== Shortcuts ===

See [[Wikipedia:WP:SHORT|WP:SHORT]]. A shortcut is a type of [[Wikipedia:WP:REDIRECT|redirect]] that provides an abbreviated link to a project page. These are useful to display along with the page name on index pages that list primarily project pages, as opposed to [[Wikipedia:WP:WIAA|articles]] or external links. For example, this would apply to index pages aimed primarily at editors of a wiki, rather than readers.

An index page itself may also have a shortcut, which becomes useful for making rapid wikilinks to major topics via their anchors, from other pages on the wiki, such as [[Wikipedia:WP:TALKPAGE|talk pages]].

<small>''To-do'': explain the above better, and generalize the following rules so they are not specific to Wikimedia Commons.</small>

* The index lists only one shortcut (of the format <code><nowiki>[[COM:COM]]</nowiki></code>) to a given project page.
* The shortcut follows immediately after the name of the policy or guideline.
* Not all project pages have shortcuts. In general, if Commons users cite a given project page frequently, someone will create a shortcut for it. Thus the index should generally display a shortcut for a page when the page itself displays the shortcut. This probably means users are citing the page, and the page is more important than pages that no one has made a shortcut for yet.

==== Index pages in article space ====

When an index page appears in article space rather than in the project [[Wikipedia:Help:Namespace|namespace]], it will not have the ordinary type of shortcut, which [[Wikipedia:WP:SHORT|on Wikipedia]] would have a prefix indicating the namespace it is in. As the article namespace has no prefix, we can use IDX: as a shortcut prefix for all index pages in the article namespace.

Shortcuts are extremely useful for index pages that someone will need to reference elsewhere, as shortcuts make it easy to link to particular major topics within the index.

== What isn't in an index ==

An index typically omits the following:

* (Most) entries solely to point to another place in the index. These are not necessary because Ctrl+F search lets you find keywords anywhere in the index.
** The index is searchable in ways that a paper index is not; it therefore doesn't have to absolutely mimic a [[Wikipedia:Index (publishing)|paper index]] to be fully effective.
*** There are a few exceptions, generally because (a) a term that is common isn't used in a page title (rare), and (b) where the term is so common that searching the index for it could be frustrating. (Example: "As of")
* An index may not list every possible topic as a major topic. An index will group pages together in a hierarchical structure (i.e., a [[Wikipedia:taxonomy|taxonomy]]), reflecting the judgment of editors on the relationships between various topics. Again, because the index is searchable, you should be able to find topics even if they appear below another topic that starts with a different letter.
* As many duplicate entries as a paper index might contain. Because the index is searchable, it does not need to repeat an entry in as many parts of the index as a paper index might.

== How to start a new index page ==

=== Choosing an index title ===

Index pages in article space should ordinarily have titles that begin with "Index of". This follows the pattern on Wikipedia of list pages titles that start with "List of", and outline page titles that start with "Outline of". See for example:

* [[Wikipedia:Special:PrefixIndex/Index of|Special:PrefixIndex/Index of]]
* [[Wikipedia:Special:PrefixIndex/List of|Special:PrefixIndex/List of]]
* [[Wikipedia:Special:PrefixIndex/Outline of|Special:PrefixIndex/Outline of]]

An index in the project namespace may have a different type of title, such as:

* [[Wikipedia:Wikipedia:Editor's index to Wikipedia|Wikipedia:Editor's index to Wikipedia]]
* [[Commons:Commons:Editor's index to Commons]]

The most common type of index article on Wikipedia is an index of articles related to a geographic or geopolitical entity such as a state or nation:

* Index of ''location''-related articles

For example:

* [[Wikipedia:Index of China-related articles|Index of China-related articles]] - which irritatingly splits the content into two separate pages, thus defeating Ctrl+F or Command+F search.

Notes:

* There seems to be no single category on Wikipedia for index pages.
* Different index pages follow different styles. Some are mere lists of article titles, while others are somewhat more hierarchical. As of 20:28, 26 July 2010 (UTC) I have not seen any index pages in the Wikipedia article space which are as well developed as the [[Wikipedia:Editor's index to Wikipedia|Editor's index to Wikipedia]].
* Some pages on Wikipedia may have the word "Index" in their titles, when the article is about some other type of index. For example:
** [[Wikipedia:Environmental Sustainability Index|Environmental Sustainability Index]] (''redirected from [[Wikipedia:Index of Environmental Sustainability|Index of Environmental Sustainability]])

=== Adding initial wikitext Template:Start new index page ===

[[Wikipedia:WP:SUBST|Substitute]] the {{Tl|Start new index page}} template onto a new page, like this:

 {{Tlsp|Start new index page}}

That will add alphabetic headings, tables of contents in each section, and a {{Tl|Notice}} at the top you can customize for the subject of a particular index.

== Comparison with automatic indexing ==

Publishing systems such as [[Wikipedia:DocBook|DocBook]] provide markup codes to assist with building [[Wikipedia:Index (publishing)|back-of-the-book style indexes]]. In these types of systems, an author adds markup codes throughout a document that tell the software to insert entries in an index that point to the locations of the markup codes. The software can then resolve the page numbers in the index during the document-publishing step. Some sort of automated pass by software is necessary to update page numbers in an index every time an author edits a document and changes its length.

Because wikis have no page numbers, but only links, an index page does not really need users to add any special markup code to the pages they index. The [[Wikipedia:MediaWiki|MediaWiki]] software that powers {{SITENAME}} provides no native tools<ref name="">[[mw:Extension:IndexFunction]] is a MediaWiki extension that provides a simple indexing capability; {{SITENAME}} does not use it for index pages.</ref> for [[Wikipedia:Index (publishing)#Embedded indexing|automatically creating index pages]]. The closest approximation is the [[Wikipedia:Help:Category|category]] link, which one adds to pages, to tell MediaWiki to then display links to those pages on a category page. However, category pages are very simple, without the hierarchical structure, cross-references, synonyms, and annotations of index pages.

Editing index pages on a wiki by hand is somewhat tedious, but allows for great flexibility in organizing an index. It also removes abstraction, by making an index editable on the index page itself. The author gets immediate feedback from previewing edits to an index. In contrast, with a publishing system that builds an index from markup codes throughout a document, the author cannot see the effect of changes to the index codes until performing the document publishing step. The author also has to imagine what the index structure will look like without being able to see it while building the structure from scattered markup codes.

Since wikis tend to evolve continuously, with many different editors contributing, index pages on wikis must also evolve. It is probably easier to have directly-editable index pages on wikis. The alternative approach of adding indexing codes to the pages to be indexed would introduce more abstraction, and probably more confusion for newer editors. Experience on the [[Wikipedia:WP:HD|Wikipedia Help desk]] shows that [[Wikipedia:Help:Category|categories]] are one of the more confusing MediaWiki features for new users. Users typically see a category page, and expect to add entries to the category page by ''editing the category page itself''. (Adding to the confusion, a category page has an "edit" link at the top, suggesting that the page contents are editable - but only the descriptive text at the top of the page is.) The actual approach of adding category codes to the pages one wants to categorize seems to violate the [[Wikipedia:Principle of least astonishment|Principle of least astonishment]] for many people.

== Comparison with other navigation aids ==

<small>''To-do'': compare index pages with lists, outlines, navigation templates, categories, and special pages.</small>

An index page is not a mere alphabetical listing of article titles, "[[Wikipedia:Index (publishing)#Purpose|but an organized map of... contents]], including cross-references, grouping of like concepts, and other useful intellectual analysis."

Index pages are a less-common navigation tool on wikis such as Wikipedia. An index page combines features of the other more common tools such as [[Wikipedia:Wikipedia:Categories, lists, and navigation templates|categories, lists, and navigation templates]]:

* [[Wikipedia:Help:Category|Categories]]: an index page is able to group some related topics together with hierarchical structure, a feature analogous to categories.
* [[Wikipedia:Help:List|Lists]] and [[Wikipedia:WP:OUTLINE|outlines]]: portions of an index page appear locally as lists. An index page is a list, with extra structure. An outline is also a hierarchical list, but without all the extra features of an index.
* [[Wikipedia:WP:NAVBOX|Navigation templates]]: a navigation box groups some related articles together, in a compact form suitable for [[Wikipedia:WP:TRANSCLUDE|transcluding]] into each of the articles. Because a navigation box must be rather small, it displays only a selective sample of related articles if the total number of related articles is large. An index, in contrast, can be comprehensive.
* [[Wikipedia:Help:Special page|Special pages]] can display links to pages having various characteristics recognizable by the [[MediaWiki]] software. Because the software generates them, and they contain no [[Wikipedia:wikitext|wikitext]], special pages lack the extra features and editorial judgment of an index page.

== See also ==

* [[Index of Appropedia]]
* [[User:Teratornis/Tasks#Index]]

== Notes and references ==

<references />

== External links ==

=== General links about indexing and more ===

==== Wikipedia articles ====

* [[Wikipedia:Controlled vocabulary]]
* [[Wikipedia:Cross-reference|Cross-reference]]
* [[Wikipedia:Index (publishing)|Index (publishing)]]
* [[Wikipedia:Library of Congress Subject Headings]]
* [[Wikipedia:Medical Subject Headings]]
* [[Wikipedia:Ontology (information science)|Ontology (information science)]]
* [[Wikipedia:Taxonomy|Taxonomy]]
* [[Wikipedia:Web indexing|Web indexing]]

==== Other sites ====

* {{Cite web|url=http://web.archive.org/web/20121116005821/http://boxesandarrows.com/view/improving_usability_with_a_website_index|title=Improving Usability with a Website Index|accessdate=2010-12-28|first=Fred|last=Leise|date=2002-07-15}}

=== Pages related to indexing on wikis ===

* [[Wikipedia:Wikipedia:Editor's index to Wikipedia/About|Wikipedia:Editor's index to Wikipedia/About]] - a page describing the [[Wikipedia:WP:EIW|Editor's index to Wikipedia]] by [[Wikipedia:User:John Broughton|User:John Broughton]] and other Wikipedia users, the design of which contains the index page elements that this page describes.
* [[Commons:Commons:Editor's index to Commons/About]] - a page describing the Editor's index to Commons, which has a structure similar to that of the Editor's index to Wikipedia.
** [[Wikipedia:User:Teratornis/Notes#Editor's index to Commons|User:Teratornis/Notes#Editor's index to Commons]] - notes about creating the Editor's index to Commons
* [[Wikipedia:Wikipedia:WikiProject Council/Directory/Wikipedia|Wikipedia:WikiProject Council/Directory/Wikipedia]] - lists some WikiProjects on Wikipedia whose aims are similar to the need our index pages address.
** [[Wikipedia:Wikipedia:WikiProject Contents|Wikipedia:WikiProject Contents]]
** [[Wikipedia:Wikipedia:WikiProject Lists of topics|Wikipedia:WikiProject Lists of topics]] - topic lists are often merely alphabetical listings by article title, with very little hierarchical grouping, and no annotative descriptions of entries.
** [[Wikipedia:Wikipedia:WikiProject Outline of Knowledge|Wikipedia:WikiProject Outline of Knowledge]] - outlines on Wikipedia have some conceptual overlap with index pages, but they are quite different.
** [[Wikipedia:Wikipedia:Categories, lists, and navigation templates|Wikipedia:Categories, lists, and navigation templates]] - compares three methods of grouping articles on Wikipedia.
*** [[Wikipedia:Wikipedia:Categorization|Wikipedia:Categorization]]
*** [[Wikipedia:Wikipedia:Lists|Wikipedia:Lists]]
*** [[Wikipedia:Wikipedia:Navigation templates|Wikipedia:Navigation templates]]
** [[Commons:Category:Commons category schemes]] - pages with hierarchical listings of categories for various subject areas on Wikimedia Commons.
* [[mw:Extension:IndexFunction]] - a MediaWiki extension that lets you build a simple index automatically by adding indexing code to the pages you want to index (i.e., [[Wikipedia:Index (publishing)#Embedded indexing|embedded indexing]]).

[[Category:Appropedia help]]