Alphabetization

Alphabetize term entries from A to Z. Entries must not be added randomly or by arbitrary ordering criteria unclear to the reader. If numerical entries are present, they precede alphabetical ones, and any symbolic entries precede both (i.e.: "!" before "1" before "A"). A Latin-based character with diacritics is alphabetized after the plain character it is based on. Non-Latin-based characters are alphabetized in order of their appearance in Unicode. Numeric entries that may appear in the article subject's context either as numerals or spelled out should be given in the form "three (3)" Do not create numerical entries unless absolutely necessary, such as the case of a definable difference between "eight-" and "8-" in the context.

Make a separate section in a stand-alone list for each letter/number if the glossary is large enough to warrant it, but group into ranges as appropriate, e.g. "X–Z". Otherwise divide the article into ranges, e.g. "0–9", "A–M" and "N–Z". Do not section an embedded list, as this impedes editing and may greatly lengthen the overall article's table of contents.

Content

Wikipedia is not a dictionary; correspondingly, explain glossary terms encyclopedically, and only rarely and sparingly add dictionary definitions to a glossary here (usually solely for the sake of completeness). Lists of dictionary definitions belong on Wiktionary; you can still link to them from our articles.

Likewise, do not add everyday words, nor specialized terms not specific to, or having a special meaning within, the topic in question.

All entries must be verifiable with reliable sources, just like any other information in Wikipedia articles.

Multiple definitions

Give two or more definitions of a term some kind of consistent identifiers. In most cases, multiple definitions should be numbered. Other conventions exist, such as identification of the sub-field to which each definition pertains, but these are rarely mutually exclusive with numbering, and numerical identification is a convenient mnemonic for readers and referent for editors.

Nearly all stand-alone, and most embedded, glossaries are good candidates for structuring. HTML, and XHTML (which Wikipedia uses), provide rich semantics for producing glossaries and lists similar to glossaries. (See HTML elements for more information on definition lists and their term and definition elements.). The examples below show how to use these elements to create Wikipedia glossaries that are accessible and which can be parsed and re-used in various ways by third party applications.

Structured glossaries require somewhat more markup, but result in cleaner and richer XHTML output from Wikipedia's MediaWiki software engine, and offer many benefits. They:

• Are more accessible to those using screen readers
• Have directly linkable entries and other editorial benefits (with a simplicity tradeoff), such as code consistency
• Enhance Wikipedia's application richness and usability
• Use semantic HTML, improving reusability of Wikipedia content by both software and people
• Will validate as both correct XHTML and HTML, ensuring the broadest browser compatibility (see #Technical notes for why this is important)
• Are technically well-formed XML, another compatibility factor
• Can be extended consistently, e.g. to include metadata, or to specially style terms and definitions
• Will be easier to reconfigure if Wikipedia decides to change site-wide formatting, as it often does.

A structured glossary does not use simplistic bullet list items, or headings and free-form text; rather; it consists of terms and definitions within flexible HTML definition list structures, defined by extensible Wikipedia templates.

Produce a structured glossary thus:

• The glossary as a whole (or each part, if broken into sections, e.g. "A–M") is surrounded by a {{gloss}} template and a corresponding {{glossend}} tag. (On the technical side, these templates together invoke the <dl>...</dl> definition list HTML structure.)
• A term is given on its own line using the {{term}} template, and is automatically boldfaced. (Technically, this invokes the <dt>...</dt> definition list term HTML element.)
• A definition is next given on its own line using the {{defn}} template, and follows either the term or a previous definition. (This markup translates into the <dd>...</dd> definition list definition HTML element.)

Do not make individual terms in a structured glossary into headings (doing so will produce garbled output). The terms will be linkable without being headings.

Use the templates as a set: {{gloss}}, {{term}}, {{defn}} and {{glossend}}. Do not mix-and-match structured glossary templates with wikimarkup definition list code (; and : style) or other markup; this does not offer any benefits at all, and the wikimarkup in particular poses severe problems for complex list development.

If a glossary consists of few entries, all with lengthy definitions, consider instead formatting the article as a heading-based non-structured glossary, a series of term sections with definitions in regular paragraphs, rather that using structured (or, for that matter, list-based non-structured) glossary format.

Formatting

Structured glossaries use semantic, accessible markup that adheres to Web standards, for reasons detailed above. Some example code, showing various formatting options, as might appear in a stand-alone glossary article divided into sections by letter of the alphabet:

As is shown in the example, multiple definitions use multiple {{defn}} templates. See the templates' documentation for the advanced features of {{term}}, {{defn}}, and {{gloss}}.

With structured glossaries (using these templates, or created manually with HTML), a definition behaves, inside its <dd>...</dd> bounds, just like normal prose and markup. Multiple paragraphs can be used with ease, and block-quotes, nested lists and other structures can be used freely, unlike with wikimarkup-based glossaries. The flexibility and power of HTML tags are much richer than those provided by wikimarkup's ; and : definition list or * unordered list features, which do not work properly due to MediaWiki bugs and misfeatures.

Bulleted-list-based

Non-structured glossaries most often take the form of simple bulleted lists, e.g.:

This easy style is often used in both embedded and stand-alone glossaries. Numbered lists (beginning with # instead of *) should not be used, as they imply a specific (e.g. hierarchical or chronological) order.

More complex glossaries are best done as structured glossaries. That said – and with an explicit understanding that doing so will produce poor-quality, easily broken code that others are likely to replace with a structured glossary – editors can use ordered and unordered list wikimarkup to squeeze a little more life out of this glossary style. This is especially appropriate in userspace drafts, stubs and other poorly developed articles, where the importance of getting basic information into an article and sourcing it greatly exceeds any formatting considerations. It is certainly better to have the information now, and convert it later when there is interest in and consensus for doing so.

Blocks of text, properly marked up, can be used for longer definitions in an un-structured glossary. Multi-paragraph definitions require the HTML <p> paragraph break (or better yet, complete {{<p>...</p>}} paragraph markup), without any wikimarkup whitespace between either passages and the break, due to Wikipedia limitations (see Wikipedia:Manual of Style/Glossaries/DD bug test cases for technical details). Example showing various extended aspects of bulleted list wikimarkup for a glossary:

Heading-based plain prose

Non-structured, stand-alone glossaries with long and detailed definitions are best formatted with entries as subheadings (a style that should not be used for embedded glossaries) with definitions given as normal prose paragraphs:

For cases in which most or all of the definitions are long, multi-paragraph explanations, this format is actually preferable to a structured glossary, as the article is only marginally classifiable as a glossary.

Number multiple definitions manually, as shown; do not use ordered lists. This glossary type especially sometimes uses non-numeric identifiers with multiple definitions. Multi-paragraph definitions are just like any other Wikipedia prose paragraphs.

Definition list wikimarkup

Avoid using definition list wikimarkup (with ; and :) for glossaries, as it is severely limited and buggy. While such lists are okay for very casual indented list creation, especially outside of articles, they do not scale. Existing examples should usually be converted to structured glossaries, since most of the work is already done. Those wishing to avoid structured formatting should in most cases use bulleted list style, which is simpler and more flexible for inexperienced, non-technical or time-pressed editors.

Layout

Glossary articles are expected to satisfy the same conditions as other articles; this will include a well-developed lead section and references.

The default Wikipedia table of contents will not be very useful with most glossaries. One solution is:

__NOTOC__{{CompactTOC8|center=yes|symnum=yes|refs=yes}}

There are a number of variants; see the documentation for Template:CompactTOC8.

Please note that the section headings must be created manually, as usual, and must exactly match the selected {{CompactTOC8}} parameters.

Each section in a lengthy glossary page should terminate with another call to {{CompactTOC8}} (or some other form of concise sectional navigation). CompactTOC8 can be used with various other parameters enabled to keep the display thin and linear and with a link to the top of the page, e.g.:

{{CompactTOC8|side=yes|center=yes|top=yes|symnum=yes|refs=yes|nobreak=yes}}

Depending upon the {{CompactTOC8}} parameters set, there may be a section for entries beginning with numerals, with symbols, or both. If present, this section should precede A. Entries that are commonly but not always found in numeric form should be given in this section and cross-referenced to it from its spelled-out name, or vice-versa, not given duplicate definitions. Example:

{{term|8 ball}}

:''See [[#eight-ball|eight-ball]].''
...
{{term|eight-ball}}

;''Also '''8 ball''', '''8-ball''', '''eightball'''.'' Definition here.

Article size and splitting

A glossary that becomes too long (more than about 100 kB) should be split into multiple articles. We do not expect readers to work their way through a glossary from head to tail, so their length need not be limited by attention span. But very large articles have technical problems: they take a long time to load, especially for editing or previewing, and they may cause some browsers to crash by demanding too much memory.

Glossaries should usually be split into roughly equal chunks, rather than attempting to convert to summary style, or thinning out by narrowing the subject of the glossary. For example, the first split of Glossary of underwater basketweaving terms could be into Glossary of underwater basketweaving terms: A–M and Glossary of underwater basketweaving terms: N–Z, but very long glossaries may need even more parts, and some glossaries will have one letter much longer than others. If there are terms beginning with numbers or symbols, they should go before A, in sections of their own, unless there are enough of them to warrant their own subarticle.

There are two good solutions for the original Glossary of underwater basketweaving terms:

• Have it redirect to the first chunk, and include the original lead there.
• Have it as a disambiguation page, with a full lead, and links to all the chunks.

In either case, the other chunks should have summaries of the full lead, so that two different leads do not evolve. The first method is simpler; the second is preferable for glossaries so long that they need more than three or four chunks, or articles formatted in glossary format but not in alphabetical order.

Care is needed in dividing glossaries into subarticles. Each subarticle must link with the ones before and after, and to the disambiguation page if there is one; {{CompactTOC8}} can help with this. Each sub-article must have its own references section, and these should be checked to be sure they still work. In particular, the first instance of a named <ref> tag in each subarticle will need its own text.

Naming conventions

For a glossary list article that consists of a simple lead and a glossary, the form Glossary of subject terms is preferred, with redirects to it from Subject terms and Subject glossary. This mirrors the more general naming convention of lists, "List of subjects".

For an article that mostly consists of a glossary list but has well-developed material on the history and use of the terminology, or other such information (several paragraphs worth), the form Subject terms is preferred, with redirects to it from Glossary of subject terms and Subject glossary.

The general advice (e.g. handling of nationalities, fictional subjects, etc.) at WP:Stand-alone lists#Naming conventions includes glossaries as well, to the extent applicable.

The sub-articles of multi-page split glossaries should follow the guidelines at WP:Naming conventions (long lists) to the extent applicable. In short, they should be named as the original (main) glossary page, with the letter or range of covered letters of the alphabet (or numbers, etc.) following a colon after this title, e.g. Glossary of underwater basketweaving terms: A–M or Curling terms: N–Z. The en-dash (–) should be used to divide the range, not a hyphen (-), em-dash (—), minus (−) or other similar character, but the hyphenated form of the article name (e.g. Curling terms: N-Z) must also exist as a redirect to the real article page.

Specialized glossaries may require a different sort of name (including for multi-part glossaries' sub-articles), e.g. Glossary of computing terms: Unix, Glossary of computing terms: Microsoft Windows, etc.

See the "Embedded glossaries" and "Non-glossary lists using glossary formatting" sections, below, for related naming issues.

A glossary included within an article may occasionally be helpful for readers, either to understand an article's terminology better, to learn more about the terminology used in a field covered by the article, or both. It may also provide a glossary that can be linked to from related articles, unless and until such time as a stand-alone glossary is warranted.

Some guidelines on including glossaries within articles, in addition to the general guidelines above:

• The glossary must be its own section, with a heading identifying it as a glossary (this is not only orderly, it allows the glossary to be linked to directly). The title of this section should conform to the both WP:Manual of Style#Section headings – do not repeat the subject in the heading . It also should not use excess verbiage ("Glossary of key terms in the discipline", etc.) – keep it simple. A plain ==Glossary== is fine in almost all cases.
• If the glossary would be 5 terms or fewer, it is probably better to define the terms concisely in context in the prose of the article, instead of using a glossary.
• If the glossary would be 25 terms or more, it is probably better to create a stand-alone glossary article.
• If the entries will be very detailed, it is probably better to use a stand-alone glossary; embedded entries should be concise.
• Embedded glossaries should not use subheadings inside them (e.g. for letters of the alphabet), and should simply be editable as a single section. If it is large enough to need subsectioning, it should probably be a separate article.

The preferred method of creating an embedded glossary is to use structured glossary templates to lay out the structure of the glossary, just as for stand-alone glossaries, as shown above, under a single clearly labeled heading (usually ==Glossary==). While this requires a bit more work that simply using bulleted lists, it provides most of the benefits of structured glossary articles, and makes it very easy to eventually move the glossary to a structured stand-alone article as the glossary grows.

For an article that is a non-glossary list that uses glossary formatting, follow the advice at WP:Stand-alone lists#Naming conventions. For the naming of multi-page, split lists, see WP:Naming conventions (long lists). Such lists sometimes need customized naming, if they are not naturally expressible as alphabetic or numeric ranges, e.g. List of automobiles: Chevrolet, List of automobiles: Ford, etc. Note, however, the standardized use of a colon, not a parenthetical, comma, dash, slash or other separator.

The {{term}} template should only be used for actual glossaries. For non-glossary lists that simply use glossary formatting, use a bare <dt>...</dt> structure, or its wikimarkup equivalent, the leading ; character:

{{gloss}}

;term 1
:Definition of term 1.

{{glossend}}

If it is desired that the terms have link anchors, use the {{anchors}} template to provide them. E.g., ;term 1{{anchors|term 1|another anchor}}

Non-glossaries often need different sectioning (numerical, topical) than a glossary, and consequently may have different table of contents needs, and for multi-page long lists, each sub-article needs inter-page navigation of some kind to other articles in the series. Some solutions include specialized compact tables of contents and custom navigation templates. Such lists may also have different section ordering needs, e.g. by date in a list of events, instead of alphabetical.