Get our free book (in Spanish or English) on rainwater now - To Catch the Rain.

Difference between revisions of "Help:Index pages"

From Appropedia
Jump to: navigation, search
(create a help page explaining how to create and edit index pages)
 
(Pages related to indexing on wikis: annotate a link)
Line 231: Line 231:
 
* [[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.
 
* [[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.
 
* [[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: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 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 Contents|Wikipedia:WikiProject Contents]] - coordinates the overall arrangement of Wikipedia's contents/navigation system.
 
** [[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 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:WikiProject Outline of Knowledge|Wikipedia:WikiProject Outline of Knowledge]] - outlines on Wikipedia have some conceptual overlap with index pages, but they are quite different.

Revision as of 20:07, 12 February 2011

An index is a system to make finding information easier. An index page on a wiki is a page that mimics a 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 general

An index page on Appropedia is an example of Web indexing.

A well-developed index page provides a comprehensive and structured[1] list of links to pages relating to a particular topic area on Appropedia. See the 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 to learn how on-wiki indexing differs from indexing in book-oriented publishing systems such as 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:

  • 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 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 Appropedia, or also to external sites. The index can have a 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 cross-references that look interesting.
  • You can do a Ctrl+F or +F search in your 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 Appropedia, 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 anchors, typically consisting of three to ten or so characters. This makes it easy to post a wikilink like this:

To-do: replace this example with one that works on Appropedia, after I build at least one index page here.

The format of the wikilink in this example is:

[[Commons:COM:EIC#Copyright]]

where "#Copyright" is an anchor within the index.

Most major topics in the index, and some of the more important subtopics, visibly display their anchor names with the {{Shortcut}} template. This makes it easy to copy a shortcut such as Commons:COM:EIC#Upload, and then paste it elsewhere on Appropedia (typically in the User:, Project: (Appropedia:), or Talk: namespaces). For example, this saves time when answering questions or discussing subject matter that the index covers. For example, the Editor's index to Wikipedia links to pages that answer most questions about using Wikipedia that appear on the 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 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:
**[[Page name of entry 1]]
** Subtopic:
***[[Page name of entry 2]]

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 moves a page), the index should also be changed. The intent of the index is to show the current name of pages, not just 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

As mentioned above, every major topic has an anchor, as a way to jump to a specific place in an index. In edit mode, these anchors look like:

<span id="Copyright"/>

or:

{{Anchor|Copyright}}

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 {{Anchor}} template simplifies the code:

<span id="Copyright"/><span id="Copyrig"/><span id="Copyr"/><span id="Copy"/>

vs:

{{Anchor|Copyright|Copyrig|Copyr|Copy}}

Anchors could have been the same as topic names, such as: <span id="Naming an article"/>. 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 +F for the anchor name.

Visible anchors

Where vertical space allows (i.e., where a major topic has at least three lines of entries below it, before the next major topic), an index should display at least one of the anchors for the major topic with a {{Shortcut}} template.

The {{subst:Shortcut}} template automatically creates an anchor (see Template:Shortcut#Anchors), but the resulting anchor is not of the best form for section anchors in an index page. On an index page, we like to make just a few shortcuts to refer to the index page itself, and then create section links from that (see for example WP:EIW which is a shortcut link to the Editor's index to Wikipedia, and WP:EIW#Cat which links to the Categories entry in the index). Thus we still need to specify our own section anchors with the <span/> tag or the {{Anchor}} template. The problem is that the {{subst:Shortcut}} template uses the entire shortcut name to act as the anchor name, but we only want the portion that appears after the Number sign (#) to be the anchor.

To-do: show an example after I build a first index page on Appropedia and have some wikitext to use as an example.

Piped links

An index should not use 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:

* Boldness: [[Commons:Don't be bold]] (essay)

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

To-do: edit this section to make more sense on Appropedia.

It is particularly important not to obscure interwiki links with piped links in index entries. When the index links to a page outside of Appropedia, the reader must be aware of this. Project pages on Wikimedia Foundation wikis (such as the English Wikipedia may not strictly apply to Appropedia, but are useful as suggestions when Appropedia has no corresponding project page to cover a certain topic which nevertheless arises on Appropedia. 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:

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

Ideally, the need for such interwiki links should decline as the Appropedia 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 WP:SHORT. A shortcut is a type of 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 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 talk pages.

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

  • The index lists only one shortcut (of the format [[COM:COM]]) 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 namespace, it will not have the ordinary type of shortcut, which 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 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 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:

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

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:

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

Adding initial wikitext Template:Start new index page

Substitute the {{Start new index page}} template onto a new page, like this:

{{subst:Start new index page}}

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

Comparison with automatic indexing

Publishing systems such as DocBook provide markup codes to assist with building 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 MediaWiki software that powers Appropedia provides no native tools[2] for automatically creating index pages. The closest approximation is the 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 Help desk shows that 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 Principle of least astonishment for many people.

Comparison with other navigation aids

To-do: compare index pages with lists, outlines, navigation templates, categories, and special pages.

An index page is not a mere alphabetical listing of article titles, "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 categories, lists, and navigation templates:

  • Categories: an index page is able to group some related topics together with hierarchical structure, a feature analogous to categories.
  • Lists and 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.
  • Navigation templates: a navigation box groups some related articles together, in a compact form suitable for 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.
  • Special pages can display links to pages having various characteristics recognizable by the MediaWiki software. Because the software generates them, and they contain no wikitext, special pages lack the extra features and editorial judgment of an index page.

See also

Notes and references

  1. Leise, Fred (2002-07-15). "Improving Usability with a Website Index". Archived from the original on 2010-12-28. http://www.webcitation.org/5vJwZDVkj. Retrieved 2010-12-28.
  2. mw:Extension:IndexFunction is a MediaWiki extension that provides a simple indexing capability; Appropedia does not use it for index pages.

External links

General links about indexing and more

Wikipedia articles

Other sites

Pages related to indexing on wikis

Wikipedia
This page or section includes content from Wikipedia. The original article was at Wikipedia:Editor's index to Wikipedia/About. The list of authors can be seen in the history for that page. As with Appropedia, the text of Wikipedia is available under the CC-BY-SA.