How to write and reference an entry in the glossary

This article explains how to add and link to entries in the MDN Web Docs glossary. It also provide guidelines about glossary entry layout and content. The glossary provides definitions for all the terms, jargon, abbreviations, and acronyms you'll come across when reading MDN content about the web and web development.

It's possible that the glossary will never be complete because the web is always changing. By contributing new entries or fixing problems, you can help us update the glossary and fill-in gaps.

Contributing to the glossary is an easy way to help make the web more understandable for everyone. You don't need high level technical skills. Glossary entries are intended to be straightforward and brief.

How to write an entry

If you're looking for topics that need a glossary entry, check the list of undocumented terms at the end of the Glossary landing page. Click any of those links to start a new Glossary page for the item you clicked. Then follow the steps below.

If you have an idea for a new glossary entry, open the button (below) in a new tab. Follow the steps listed below the button:

Step 1: Select a term to explain

Choose a term to add to the glossary. If you don't know which terms need definitions, you can view a list of suggestions. Click any term to get started! If you're already logged in, clicking the term opens the MDN editor.

Step 2: Write a summary

The first paragraph of any glossary page is a simple and short description of the term. Preferably, this should be no more than two sentences. Make sure anyone reading the description can immediately understand the defined term.

Note: Please don't copy-and-paste from other definitions or content on the Internet. (And especially not Wikipedia, since its range of license versions is smaller and incompatible with MDN.) Your glossary entry should be original content.

Writing a good glossary entry

Add a few extra paragraphs if you must, but it's easy to find yourself writing an entire article. Writing an article is fine, but please don't create it in/for the glossary. If you aren't sure where to put your article, feel free to reach out to discuss it.

There are a few simple guidelines to consider for writing a better glossary entry:

  • When you use terms in the glossary's description of the term or when you use abbreviation, you should create appropriate links. Often, this just involves creating links to other pages in the glossary. (See below: How to use the Glossary macro.) For terms directly related to the glossary entry's term, link to MDN Web Docs' main article.
  • Use appropriate related terms (with links) in the glossary entry, if it can be done without making the article difficult to follow. Having a good network of related and useful links makes a page—or set of pages—much easier to use.
  • Think about the search terms you would choose if you wanted to find this page. Try to use all the words you would use to search for the term, but without making the glossary entry nonsensical, long, or difficult to read.

Specifying the tooltip

As it is with most MDN links, hovering your cursor over a glossary link shows a brief description of the page. (In this case, it is a short summary of the term's definition.) By default, the tooltip takes the text from the entire first paragraph of the glossary entry. This is usually too long.

As an alternative, you can assign a subsection of text as the page summary (which also becomes the tooltip text). Select one or two sentences that summarize the definition of the term, adding the SEO Summary style to the selected text. This defines the tooltip text. It also assigns the text sent to search engines as a summary of the page contents. For that reason, specifically selecting a page summary helps your work become more visible in search results.

Note: Ideally, the text selected for SEO summary should be 150-160 characters. Less is better than more.

A glossary entry should always end with a Learn more section. This section should contain links to help the reader move forward: discovering more details; learning to use the relevant technology.

It is good practice to organize the links into three groups:

General knowledge
These links provide higher-level information about the term or topic. For example: a link to a relevant Wikipedia page.
Technical reference
These links offer in-depth technical information, on MDN Web Docs or other sites.
Learn about it
These are links to tutorials, exercises, examples, or any other instructional content that helps the reader learn.

Dealing with disambiguation

Some terms can have multiple meanings depending upon context. To resolve ambiguity, follow these guidelines:

  • The term's main page must be a disambiguation page containing the GlossaryDisambiguation macro.
  • The term has subpages that define the term for different contexts.

Let's illustrate this with an example. The term signature can have different meanings in at least three different contexts: security, function, and email.

  1. The page Glossary/Signature is the disambiguation page with the GlossaryDisambiguation macro.
  2. The page Glossary/Signature/Security is the page defining a signature in a security context.
  3. The page Glossary/Signature/Function is the page defining a function signature.
  4. The page Glossary/Signature/Email is the page defining an email signature.

How to use the {{Glossary}} macro

The glossary is more useful when people can access the definitions from another document. Please link to the glossary using the Glossary macro:

Macro Result Note
{{Glossary("browser")}} browser When text matches the term to be defined, just use the macro as-is. (It's case insensitive.)
{{Glossary("browser", "Web browser")}} Web browser To display alternative text, use the second argument to specify the alternative text.
{{Glossary("browser", "Web browser", 1)}} Web browser Specify 1 as an optional third argument to display the link as an ordinary link instead of a hint.

Links created with the {{Glossary}} macro display a tooltip containing the glossary entry's summary paragraph, or the text defined as the SEO summary (as described in a prior section Specifying the tooltip).

Using the macro wisely

In many cases, it's perfectly safe to use the Glossary macro anywhere on MDN. Consider these guidelines for using the {{Glossary}} macro :

  • If a term already has a link to an appropriate page on MDN, don't replace the link with a glossary link.
  • Within an article section, use the {{Glossary}} macro only once for the same term. You can recognize article sections by the way an article section always starts with a title.