Glossaries

Adding glossaries to articles

First consider whether the term genuinely needs a glossary or whether you can rewrite your sentence using plain English. Our chapter on Writing for our audience includes guidelines on using plain English – note in particular the advice on using language that's appropriate for our audience.

Next check in the CMS whether a glossary asset already exists for the term you want to explain.

If there is an existing glossary asset, check whether the explanation it gives is still relevant and accurate. If it is, note the glossary asset number in the body copy of the article using the green square bracket system. If the term needs updating, note the glossary asset number in the body copy of the article using the square bracket system, but also note the required updates at the bottom of the article.

Finally, if an existing glossary asset isn’t available, write a new one using the Writing glossaries guidelines below.

Writing glossaries for body copy

The principles of good web writing apply. In particular:

• • Use plain English. Although glossary assets can and should be used to explain technical or specialist information – for example, terms related to nutrition – you should try to use language that all users will be able to understand. 

  • Be succinct. Remember that terms appear on screen as a small window, so they shouldn’t contain too much information. 

  • Use the inverted pyramid. The most important information should appear at the beginning of the glossary. 

  • Begin the glossary with a sentence fragment. Although glossary assets aren’t dictionary entries, the first grammatical chunk of a glossary should be written in the style of a dictionary entry – that is, as a sentence fragment. Subsequent chunks should be written as full sentences.

For example:

inflammatory bowel disease (IBD)

A group of conditions that cause inflammation – that is, redness, swelling and pain – and sometimes ulcers in the digestive tract. The two most common types of IBD are Crohn’s disease (an inflammation of the full thickness of the bowel wall) and ulcerative colitis (an inflammation confined to the inner lining of the large bowel).

last milk

Milk the baby gets towards the end of a breastfeed. Last milk is rich, creamy and has essential fatty acids and lipids.

Snapchat

An app for sharing photos and videos and for chatting by text, voice or video over wi-fi. Users can take photos, record videos, add text and drawings, and send them to a controlled list of viewers. Users set a time limit – up to 10 seconds – for how long viewers can see their photos, but viewers can take a screenshot and save the photo. 

Points to note about adding glossaries

• • Add glossaries only to body copy – that is, don't add them to key points.

  • Use only one link per term per article. If a glossary term occurs many times in an article, add the link only to the first or most prominent instance. 

  • Don’t overdo it. The green underline style of glossaries attracts attention, so adding too many glossary links to various terms might distract users from the article's key messages. 

  • Don’t add images or links within glossaries - at the moment, the glossary asset doesn't support these.

Writing coarse language glossaries for movie reviews

Use the following standard format for creating and writing a coarse language glossary for a movie review:

Glossary filename: [movie name] coarse language

Glossary content:

Coarse language in [movie name] includes

Name-calling includes

Crude behaviour includes

For example:

Coarse language in Black Widow includes ‘shit’, ‘bullshit’, ‘stupid’, ‘ass’, ‘douche bags’, ‘bitch’, ‘damn it’ and ‘goddamn it’.