Glossaries in the TechNet Wiki help define terms and acronyms commonly used in various Microsoft technologies. New terms and acronyms come into usage frequently. Adding new entries to an existing glossary can be a challenge. This article details recommended procedures to maximize the usefulness of our glossaries.

Table of Contents

Introduction

When we add an entry to a glossary, of course we want the text to be accurate. We also want to be able to cross-link our entry in other Wiki articles. This requires that all entries in the glossary have named anchor tags.

In the near future the Wiki platform is expected to change. Some of the steps in this article may require modification. The images may also need to be updated. But the basic principals should remain unchanged.

↑ Return to Top

Recommendations

To make our glossaries most useful, the following are recommended practices to be aware of when adding entries.

  • All entries should be in alphabetical order.
  • All entries are grouped by the first letter of the term or acronym under a heading that is simply the letter in bold. This heading will be linked to a Table of Contents near the top of the glossary. This makes it easier for users to navigate to the term they are interested in. The Table of Contents and the letter headings should already be setup in any existing glossary. You only need to insert your new entry alphabetically.
  • Each entry should consist of two paragraphs. The first paragraph is simply the term or acronym. The second paragraph is the definition of the term or the expansion of the acronym. Sometimes this paragraph will include a hyperlink to a resource that further describes the entry.
  • The first paragraph with the term or acronym should be in bold. Use the default font.
  • If the entry is an acronym, the second paragraph should expand the acronym, with the letters of the acronym in bold. For example, if the first paragraph of the entry is: AD, then the second paragraph would start with: Acronym for Active Directory.
  • Avoid pressing the "Enter" key to start new lines or add space between paragraphs. This may look fine in the Design editor, but it introduces line break tags (the <br> tag) in the HTML. A bug in the Wiki platform causes these tags to be duplicated (in most editors) every time the article is saved. This creates unwanted white space that grows over time. Steps to avoid this are described later.
  • Each entry should have a corresponding anchor tag in the first paragraph (the term or acronym). The anchor tag name should match the term or acronym. This allows us to cross-link. We want to be able to link the term in another Wiki and have the reader navigate to our description of the term or acronym in the glossary. This can only be done if each entry has a named anchor tag. See Wiki: Cross-Linking.
  • The anchor tag name should be the same as the term or acronym, except that space characters should be replaced by the underscore, the "_" character. Spaces are not allowed in anchor tag names. Also, anchor tag names should be unique in the article.
  • Avoid unnecessary HTML referring to classes and formatting that we don't need in the TechNet Wiki. This can result when we copy content from another source. It makes it difficult to edit the HTML later, and is generally ignored by the Wiki platform.

 

↑ Return to Top

Typical Glossary Entries

The image below shows a few typical entries in a glossary. First we see the last two entries starting with the letter "K". Then we see the heading line for the entries that begin with the letter "L". Finally we see the first two entries that start with "L".

↑ Return to Top

Adding Entries in the HTML Editor

It can be easier to add entries using the HTML tab of the Wiki editor. A template for a glossary entry in HTML follows. Note that there are two paragraphs.

<p><a name=""></a><strong></strong></p>
<p>Acronym for <strong></strong>ocal <strong></strong> <strong></strong>. </p>

For example, here is an entry for the term "LAN". It includes a hyperlink to an article in Wikipedia.

<p><a name="LAN"></a><strong>LAN</strong></p>
<p>Acronym for <strong>L</strong>ocal <strong>A</strong>rea <strong>N</strong>etwork. See <a href="http://en.wikipedia.org/wiki/Local_area_network">Local area network</a>.</p>

The steps to add an entry on the HTML tab are:

  1. Open the glossary Wiki and click the "Edit" tab. This will open the Wiki in the editor, as seen below.

  2. Select the "HTML" tab near the bottom to edit the HTML and navigate to the location where you want to add the new term or acronym. In this case we plan to insert an entry for "LANMAN" right after the existing entry for "LAN", as noted in the image below.

  3. Insert the HTML for the two paragraphs of a new entry, as seen below. Each paragraph begins with a <p> tag and ends with a </p> tag. Enter each paragraph on its own line in the HTML editor.

     

    Blank lines and indenting are ignored by browsers, so format the text for readability. Also note the anchor tag name, "LANMAN" in this case. All bold text is enclosed with <strong> and </strong> tags. Also, this example includes a hyperlink to another source. The title of the hyperlink is enclosed by <a> and </a> tags. The href variable specifies the url to the link, in this case a Wikipedia article.
  4. Next, switch to the "Design" tab to make sure your new entry appears as expected.

  5. Click the "Save" button to save your work.

 

A good idea would be to work on the text of your entry, complete with the necessary HTLM, in a text file. Save it with *.htm extension. You can make as many entries as you need in the same file. Then open the *.htm file in a browser to see how it looks. The fonts will be different, but otherwise you can see if it renders as you expected. Then you can paste the contents of the file into the HTML tab of the glossary Wiki.

A few characters in the text of an entry will not render correctly in all browsers. The following table shows what should be entered in place of each problem character. This is only necessary when you are entering text on the HTML tab of the Wiki editor.

Character Substitute
> &gt;
< &lt;
" &quot;
& &amp;

↑ Return to Top

Adding Entries in the Design Editor

Many people prefer to work on the "Design" tab of the Wiki editor. There are more steps this way, but the following yields the same results.

  1. Open the glossary Wiki and click the "Edit" tab. This will open the Wiki in the editor.
  2. On the "Design" tab, navigate to the location where you will add your entry, as seen below.

  3. Place the insertion point at the very end of the line before your new entry. In this case, since we intend to add the acronym "LANMAN" after the existing entry "LAN", we place the insertion point just after the final period after the hyperlink "Local area network". Do not press "Enter".
  4. Enter your new term or acronym on the same line.
  5. Highlight the text you just entered, as seen below.

  6. At the top of the editor select "Normal" from the pull down menu, as seen above.
  7. The display will move, so navigate back to the text you entered. It will be in a new paragraph.

  8. Place the insertion point just after the term or acronym you entered. In this case, we place the insertion point just after the acronym "LANMAN".
  9. Enter the description of the term or acronym on the same line.
  10. Highlight this new text, as seen below.

  11. Again select "Normal" from the pull down menu at the top, as seen above.
  12. Navigate back to your new entry. You have now added two new paragraphs, as seen below, without adding any line break tags.

  13. Place the insertion point at the very beginning of the line (paragraph) with the term or acronym. In this case, we place the insertion point just before the acronym "LANMAN". Do not highlight anything.
  14. Click the "Hyperlink Manager" button at the top of the editor.

  15. Click the "Anchor" tab in the Hyperlink Manager.

  16. Enter the anchor tag name for your entry. This should match the term or acronym, but with any spaces replaced by underscores (the "_" character).
  17. Click "OK".
  18. Now bold any text that requires it. Highlight the text and click the "B" button at the top of the editor.

  19. If you entered text for another source that should be hyperlinked, highlight this text (the title of the source), as seen below.

  20. Click the "Hyperlink Manager" button.
  21. In the field labeled "URL" enter the url of the source web page.

  22. Click "OK".
  23. Make sure your new entry appears as expected.

  24. Click the "Save" button to save your work.

↑ Return to Top

Letter Headings

You should not need to modify the letter headings, one for each letter of the alphabet, in the glossary. However, a typical heading uses HTML similar to below.

<p>&nbsp;</p>
<h1><a name="L"></a>L</h1>

Each letter heading consists of one line with a named anchor tag, for use by the Table of Contents. There is a blank paragraph, consisting of the space character, before each letter heading. This provides the desired spacing without adding any line break tags.

↑ Return to Top

See Also

↑ Return to Top

Other Resources

↑ Return to Top