The MDN glossary is the place where we define all the terminology, jargon, and abbreviations used in documentation and coding. Contributing to the glossary is a simple way to make the Web easier for everyone to understand. You don't need a high level of technical skill to write glossary entries because they should stay simple and straightforward.
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 , just open the following button in a new tab, and then follow the steps below the button:
Step 1: Write a summary
The first paragraph of any glossary page is a simple and short description of the term (preferably no more than two sentences). Make sure anyone reading the description can understand the defined term immediately.
Note: Please don't copy-and-paste definitions from elsewhere (especially not Wikipedia, since its range of license versions is smaller, and thus incompatible with that of MDN). It's really important to make sure this content is simple and easy to understand. It's worth spending some time on it rather than stealing content blindly. This glossary should be useful new content, not repeating things from elsewhere.
Links to the glossary entry will use these summaries inside their tooltips, so that readers can see the definitions without navigating away from the page they're on. (See below how to insert links to glossary entries with the {{Glossary}} macro.)
If you must, you can add a few extra paragraphs, but it's very easy to find yourself writing a whole article. Writing a whole article is fine, but please don't put it in the glossary. If you aren't sure where to put your article, feel free to reach out to discuss it.
Step 2: Expand with links
Finally, 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, and so on.
We recommend that you sort the links into at least these three groups:
- General knowledge
- Links that provide more general information; for example, a link to Wikipedia is a good starting point.
- Technical reference
- Links to more in-depth technical information, on MDN or elsewhere.
- Learn about it
- Links to tutorials, exercises, or any other materials that help the reader learn to use the technology behind the defined term.
Suggested terms
So you want to contribute but you don't know which terms need to be defined? Here's a list of suggestions. Click one and get started!
Dealing with disambiguation
Sometimes, a term has several meanings depending on the context. To resolve the ambiguities, you must follow those guidelines:
- The term's main page must be a disambiguation page containing the
GlossaryDisambiguationmacro. - The term has subpages that define the term for a given context.
Let's illustrate that with an example. The term signature can have different meanings in at least three different contexts: security, function and email.
- The page Glossary/Signature is the disambiguation page with the
GlossaryDisambiguationmacro. - The page Glossary/Signature/Security is the page defining a signature in a security context.
- The page Glossary/Signature/Function is the page defining a function signature.
- The page Glossary/Signature/Email is the page defining email signature.
How to use the {{Glossary}} macro
The glossary is much more useful when people can access the definitions from another document without navigating away from what they're reading. Therefore we urge you to link to the glossary whenever you can, using the Glossary macro:
| Macro | Result | Note |
|---|---|---|
| {{Glossary("browser")}} | browser | When a 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 an alternative text, use the second argument to specify that text |
| {{Glossary("browser", "Web browser", 1)}} | Web browser | Specify 1 as an optional third argument to display the link as a regular link rather than a subtle hint |
Links created with the {{Glossary}} macro always display a tooltip containing the glossary entry's summary paragraph.
Usage guidelines
In many cases, it's perfectly safe to use that macro everywhere on MDN. However, there are a few cases you should handle with care:
- If a term is already linked to another part of MDN, leave it that way and do not use the {{Glossary}} macro.
- Within an article section, use the {{Glossary}} macro only once for the same term (hint: a section always starts with a title).