Revision 836363 of How to write and reference an entry in the glossary

<p>The MDN <a href="/en-US/docs/Glossary">glossary</a> 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.</p>

<h2 id="How_to_write_an_entry">How to write an entry</h2>

<p>To begin a new entry, just open the following button in a new tab, and then follow the instructions below the button:</p>

<p>{{MDNButton("Write a new entry to the glossary", "/en-US/docs/new?parent=4391")}}</p>

<h3 id="Step_1_Write_a_summary">Step 1: Write a summary</h3>

<p>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.</p>

<div class="note">
<p><strong>Note:</strong> 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.</p>
</div>

<p>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.)</p>

<p>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 <a href="/en-US/docs/MDN/Community#Join_our_mailing_lists">reach out to discuss it</a>.</p>

<h3 id="Step_2_Expand_with_links">Step 2: Expand with links</h3>

<p>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.</p>

<p>We recommend that you sort the links into at least these three groups:</p>

<dl>
 <dt>General knowledge</dt>
 <dd>Links that provide more general information; for example, a link to <a href="https://wikipedia.org/">Wikipedia</a> is a good starting point.</dd>
 <dt>Technical reference</dt>
 <dd>Links to more in-depth technical information, on MDN or elsewhere.</dd>
 <dt>Learn about it</dt>
 <dd>Links to tutorials, exercises, or any other materials that help the reader learn to use the technology behind the defined term.</dd>
</dl>

<h2 id="Suggested_terms">Suggested terms</h2>

<p>So you want to contribute but you don't know which terms need to be defined? <a href="https://developer.mozilla.org/en-US/docs/Glossary#Contribute_to_the_glossary">Here's</a> a list of suggestions. Click one and get started!</p>

<h2 id="Dealing_with_disambiguation">Dealing with disambiguation</h2>

<p>Sometimes, a term has several meanings depending on the context. To resolve the ambiguities, you must follow those guidelines:</p>

<ul>
 <li>The term's main page must be a disambiguation page containing the {{TemplateLink("GlossaryDisambiguation")}} macro.</li>
 <li>The term has subpages that define the term for a given context.</li>
</ul>

<p>Let's illustrate that with an example. The term <em>signature</em> can have different meanings in at least three different contexts: <em>security</em>, <em>function</em> and <em>email</em>.</p>

<ol>
 <li>The page <a href="/en-US/docs/Glossary/Signature">Glossary/Signature</a> is the disambiguation page with the {{TemplateLink("GlossaryDisambiguation")}} macro.</li>
 <li>The page <a href="/en-US/docs/Glossary/Signature/Security">Glossary/Signature/Security</a> is the page defining a signature in a security context.</li>
 <li>The page <a href="/en-US/docs/Glossary/Signature/Function">Glossary/Signature/Function</a> is the page defining a function signature.</li>
 <li>The page <a href="/en-US/docs/Glossary/Signature/Email">Glossary/Signature/Email</a> is the page defining email signature.</li>
</ol>

<h2 id="How_to_use_the_Glossary_macro">How to use the \{{Glossary}} macro</h2>

<p>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 {{TemplateLink("Glossary")}} macro:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Macro</th>
   <th scope="col">Result</th>
   <th scope="col">Note</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>\{{Glossary("browser")}}</td>
   <td>{{Glossary("browser")}}</td>
   <td>When a text matches the term to be defined, just use the macro as is (it's case insensitive)</td>
  </tr>
  <tr>
   <td>\{{Glossary("browser", "Web browser")}}</td>
   <td>{{Glossary("browser","Web browser")}}</td>
   <td>To display an alternative text, use the second argument to specify that text</td>
  </tr>
  <tr>
   <td>\{{Glossary("browser", "Web browser", 1)}}</td>
   <td>{{Glossary("browser","Web browser",1)}}</td>
   <td>Specify <code>1</code> as an optional third argument to display the link as a regular link rather than a subtle hint</td>
  </tr>
 </tbody>
</table>

<p>Links created with the \{{Glossary}} macro always display a tooltip containing the glossary entry's summary paragraph.</p>

<h3 id="Usage_guidelines">Usage guidelines</h3>

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

<ul>
 <li>If a term is already linked to another part of MDN, leave it that way and do not use the \{{Glossary}} macro.</li>
 <li>Within an article section, use the \{{Glossary}} macro only once for the same term (<em>hint: a section always starts with a title</em>).</li>
</ul>