Tag Archives: text

26 tips for planning, writing and editing a glossary

By Hazel Bird

Glossaries are commonly found in a huge variety of publications, from textbooks to technical reports and from encyclopedias to essays. A good glossary can serve a number of purposes that benefit both writers and readers:

  • provide a quick reference to key concepts
  • avoid the need to duplicate definitions of key concepts in multiple locations
  • increase the accessibility of a text and thereby avoid alienating less knowledgeable readers
  • enhance the experience of more knowledgeable readers by avoiding cluttering a text with what may (to them) be basic definitions
  • help groups of co-authors to write consistently on a topic.

But a good glossary is too often an afterthought – thrown together at the end of the writing process with little consideration of how it can help to underpin a text and amplify its authority.

This post looks at how to plan, write and edit a glossary that will enhance a text and be helpful to readers. But first, a post on glossaries would be remiss if it didn’t include its own glossary:

DefinitionThe part of a glossary that tells readers what a term means.
EntryOften used to refer to a term and its associated definition as a whole.
GlossThe verb form of glossary. If you gloss a term, you provide a definition of it.
GlossaryA list of definitions of technical terms used in a text.
TermA word deemed to be of sufficient importance or complexity to require an entry in the glossary.
TextThe larger body of words of which the glossary is a part (eg a book).

It’s worth saying that although the stages below can be a helpful way of dividing up work on a glossary, it makes sense to keep all the stages in mind at all times. For example, it doesn’t hurt to decide your preference on capitalisation during the planning stage. And, equally, there’s no point developing a comprehensive plan if the writer(s) and editor(s) then ignore it!

Planning your glossary

A good glossary is based on a well-planned strategy. Questions to consider when planning a glossary include the following:

1. Why are you considering providing a glossary? Would the text genuinely benefit from a glossary as an added help to the reader? Or would the glossary primarily serve to cover up uneven, unclear or incomplete writing that would be better amended before seriously considering how a glossary would fit in?

2. What level(s) of knowledge do you expect your readers to have? Do you need to gloss basic terms or only the more advanced?

3. What level of detail do you want your definitions to have? It can help to set a nominal word or line limit.

4. If your text has multiple chapters, will you have one central glossary or chapter-specific glossaries? If you prefer a central glossary, do the chapters use the same terminology or will any revisions be required to standardise terms that will appear in the glossary?

5. If your text has multiple authors or topics, how will you ensure consistency between their glossaries? Would it be helpful to provide a few sample glossary entries (taking account of the suggestions for writing and editing below)?

6. Will the glossary be allowed to define abbreviations or will these appear in a separate list? For example, if your text talks about JSON, do you want to have (a) a glossary entry that provides the full form (JavaScript Object Notation) and then talks a bit about its use in software development, (b) an entry in a separate list of abbreviations that simply provides the full form or (c) both?

7. Will cross-referencing between glossary terms be allowed (or required)? For example, the glossary of glossaries at the start of this post uses italics to cross-reference to other entries. This lets readers know a term is explained elsewhere in the glossary (and often means you can be more economical in your definitions).

8. Where will the glossary appear and how will readers access it? Common schemes include: (a) simple standalone glossary with no links to the text, (b) standalone glossary with hyperlinks and/or special formatting (e.g. colour or bold) on glossary terms in the text and (c) glossary entries on the same pages as their associated terms (common in textbooks). Which would be most suitable for your text?

9. How will readers know your glossary exists? Will you put a note at the start of the text (or even at the start of each chapter or section, if your text has subdivisions)? What will be the best balance between making information easily accessible and avoiding clutter? You can’t assume that readers will understand that bold (for example) means that there is a glossary and that the bold word is glossed within it – you have to tell them what the bold means.

Writing your glossary

Once you have a solid plan to work from, you can actually start writing your glossary (or ask your contributors to submit entries to you). Following are some do’s and don’ts of glossary writing:

10. Do consider how your terms are actually used in the text. There’s no point having a glossary term for ‘information architecture’ if the text only ever refers to ‘architecture’.

11. Do use parallel structure. For example, will you start definitions with ‘X is an …’ or just ‘An …’? This issue is connected with presentation too: usually, the longer form is only necessary if you plan to run the glossary terms into the definitions. For example:

Agile  A method of software development that occurs in stages, with the product evolving as the project progresses. (Separated style)

Agile is a method of software development that occurs in stages, with the product evolving as the project progresses. (Run-on style)

12. Do think about the grammatical forms of words. For example, it might look inconsistent to have a definition for ‘coder’ (noun) alongside one for ‘developing’ (verb). Unless there’s a good reason, it might read better to choose either ‘coder’ and ‘developer’ or ‘coding’ and ‘developing’.

13. Don’t use the word in the definition – usually. Sometimes it works, where you decide to explicitly re-state the term in the definition for grammatical reasons (as I did above in my definition of ‘gloss’). But usually it’s bad practice as it assumes knowledge on the part of your readers that they might not have. For example, you might include the following definition:

software development  Using computer code to develop digital applications and infrastructure.

Here, you’d only really have glossed ‘software’ and you’d be assuming your readers know what ‘develop(ment)’ means in the context of computing.

14. Don’t make the definition so complicated that the reader has to look it up to understand it. (Or, if you need to use technical terms, consider defining them elsewhere within the glossary and including cross-references – see point 7 above.)

15. Don’t include Wikipedia content (or similar) – anyone can do an internet search for a generic Wikipedia definition. Glossaries add value for the reader by framing each term in a way that is nuanced to reflect the content of your text.

16. Don’t quote other sources in your definitions, unless they offer uniquely relevant perspectives or you have a special reason for doing so. This can reduce the sense of authoritativeness of your text.

17. Don’t repeat definitions from the text. Readers will be frustrated if they go to the glossary in search of further explanation and just find what they’ve already read.

Editing your glossary

Glossary editing often takes place over multiple stages. First, the person who wrote the glossary (or who is collating it from multiple contributors) checks that the content is suitable and that there are no glaring holes or inconsistencies of approach. Then, another person (often a copyeditor or proofreader) conducts a more zoomed-in check to sculpt the glossary into its final form. Each will likely need to look at the following points to some degree:

18. Does the glossary adhere to each point of the plan? If not, is the divergence acceptable (perhaps something has changed since you created the plan) or do you need to adjust the entries?

19. Is the coverage logical, consistent and comprehensive? For example, have all terms of the same type been included? (So, if you’ve glossed XML, you’ll probably want to gloss HTML too if your text uses both terms.) Are there any often-used terms that are not glossed but should be? If one of the glossary’s functions is to gloss little-used terms to avoid cluttering the text with explanations, have all of these been identified?

20. Will your alphabetisation be intuitive to readers? For example, will your readers expect to find a general explanation of the syntax used in computer coding under ‘language’ or ‘programming language’?

21. Do you need any ‘see’ entries? If readers might look for the same term under two different phrases, you could choose to include both. For example, you could have a definition of the term ‘language’ but also cross-reference to it further down as follows:

language  Words and other notation used according to a pre-defined structure to create computer programs.

programming language  see language

22. Is every term in the glossary actually used in the text? See also points 10 and 12.

23. Have the glossary terms been indicated in the text where applicable (see point 8)? And are you doing this on every occurrence of each term or only (for example) at first use in the text or chapter?

24. Is the punctuation consistent? For example, will your definitions end with a full stop? This may depend on the length of the definitions. Single-sentence glossaries can end with nothing, but multiple-sentence glossaries usually look best with full stops. If you have a mixture, it’s best to be consistent and include full stops for all of them.

25. Is the capitalisation consistent? Will you capitalise all of your glossary terms (eg ‘Debugging’ and ‘Python’) or only proper nouns (eg ‘debugging’, but ‘Python’)?

26. Does each definition read well and follow whatever spelling and other stylistic conventions have been used in the main text? When they think about what goes into editing a glossary, many people jump straight to this point. But, in reality, it’s just the last item in a long list of other considerations.

Planning, writing and editing a good glossary is a complex and time-consuming process. Throwing together a glossary at the last moment is a wasted opportunity and may even detract from the reader’s experience – for example, by raising expectations that are not met (eg because the glossary is of poor quality and isn’t tailored to the text) or creating frustration (eg if the glossary is difficult to access or navigate, or equivalent terms are not glossed).

Thinking about your glossary from the start of the creation process will make it an integrated and cohesive part of your text, and enhance the text’s value and authority for your readers.

Hazel Bird is a project manager, copyeditor and proofreader who has happily edited glossaries that followed all of these tips and others that followed none. She regularly works on computing books (hence the examples above) but also edits widely across business, public sector and academic publishing.

 


Have you seen our recent focus paper by David Crystal on why it’s worth using a professional editor? It’s one of CIEP’s many fact sheets and focus papers for editorial and publishing professionals.


Photo credits: Open book by by Jonas Jacobsson; Software development by Hack Capital, both on Unsplash

Posted by Abi Saffrey, CIEP blog coordinator.

The views expressed here do not necessarily reflect those of the CIEP.

25 tips for writing effectively for older readers

Vera

Sarah Carr’s friend, Vera, celebrating her 100th birthday – when she was born in 1911, the UK had 102 centenarians; by 2013, it had 13,780.

Misleading information, unclear instructions, technical jargon and illegible print: these are all barriers that can stop older people accessing products and services. Apart from the obvious ethical problem – it is unacceptable for a civilised society to withhold important goods from citizens – it makes good business sense to value older consumers. The 65-plus age group represents 20% of the UK consumer population (those aged 16 and above) and is expected to rise to 25% by 20301.

As experts in written communication, members of the Society for Editors and Proofreaders (SfEP) are well equipped to help ensure that texts meet the needs of target readers. The SfEP is launching a three-tier commercial package for organisations targeting older consumers. Comprising a communications audit, editorial consultancy and in-house training, the project kicks off with the publication of a booklet on communicating with older readers. Drawing on research and anecdotal evidence gathered with the help of SfEP members and editors from other English-speaking countries, Sarah Carr presents in this blog a list of 25 top tips. For more ideas, and advice on how to implement these in your work, watch out for the booklet!

Attitude

  1. Do what you can to challenge attitudes towards ageing and older people.

Features of older people

  1. Understand the needs of older readers, remembering that they have widely varying abilities, and encompass two or even three generations.

Inclusive writing

  1. Take an inclusive approach to writing, suitable for all members of the public (sometimes known as ‘plain language’).

Purpose, content and structure

  1. Before you start writing, think about why you are doing so, what you want the text to achieve, and the best medium for this purpose.
  2. Plan your messages and ideas, ensuring they are clear and honest.
  3. Organise the content logically, using an appropriate structure and good navigational aids, and avoiding very long paragraphs.

Style and grammar: words and phrases

  1. Consider using graphics to help present your ideas.
  2. Omit redundant words, and use short, familiar words and phrases.
  3. Use jargon and abbreviations only when necessary, and explain each term when you first mention it.
  4. Ensure that you refer to people equally; failing to do so may not only offend readers (and so lose their attention) but also helps prolong inequality.

Style and grammar: sentences

  1. Ensure that you use good grammar, spelling and punctuation.
  2. Aim for an average sentence length of 15 to 20 words, with some longer and shorter for variety and effect.
  3. Use strong verbs (rather than nominalisations/deverbal nouns, e.g. ‘decide’, not ‘make a decision’).
  4. Favour active verbs (‘the team decided’, not ‘it was decided by the team’), writing in the first and second person (‘I’/‘we’ and ‘you’) and phrasing points positively.

Layout and design

  1. Use a simple, clear font, in sentence case, at a size of 12 to 14 point, avoiding italics and underlining.
  2. Align text to the left, with lines of a reasonable length, and avoid splitting words between lines.
  3. Use white space effectively, for example to help show the logical structure of your text.
  4. For text on paper, use good-quality paper with a matt finish, ensuring a good level of contrast between background and ink colours.
  5. Keep images clear and simple, ensuring they do not stereotype older people.

Writing for the web

  1. Ensure it is easy to understand the structure of your website, and to navigate around the site.
  2. Think about web-specific aspects of layout and design, and the readers’ familiarity with using computers and the internet.
  3. Include text alternatives, e.g. audio and video.

Checking the suitability of your text

  1. Aim for a reading-age level of 12 to 14 years, using a readability formula (available in Word).
  2. Consider testing your text on a real audience, if time and money allow, or otherwise using plain-English editors to provide an expert opinion.

Acquiring or commissioning the skills

  1. For a professional and cost-effective service, commission support from SfEP members. And don’t forget our specialist training courses and publications!

1 Analysis by the Personal Finance Research Centre at Bristol University quoted in Age UK (2010) Golden Economy: The Consumer Marketplace in an Ageing Society (research by ILC-UK).

Sarah CarrSarah Carr works as a writer, editor and proofreader, specialising in plain English and business communication. She feels strongly that our society should value old age and older people more, and is saddened by its mysterious obsession with youth. As a practical demonstration of her principles, she refuses to dye her (increasingly) grey hair!

Proofread by SfEP ordinary member Louise Lubke Cuss.

The views expressed here do not necessarily reflect those of the SfEP.