Glossary style guidelines

Do the best you can. Editors will smooth things out.

Punctuation and spelling

We do things the Oxford University Press way, more or less (these instructions aside). For the most part this means punctuation is outside quotaton marks, and British-English spelling conventions are used for most words (i.e. "dialogue" instead of "dialog", "colour" instead of "color", and so on) except it's "z" (e.g. ‑ize) instead of "i" (e.g. –ise) for words originating from Greek (see explanation). For words originating from Latin, the "s" is retained. When in doubt, use "z".

Style and tone

Write with a friendly style without too much personality. Use plain language. Use short sentence as much as you can, but don't kill a long sentence if it works well. We approve of our voice sentiments too.

Construction

Write the body of your definitions from general to specific concepts with the following in mind:

Original composition:

Definitions should not be copy/pasted from another source, and they should be better efforts than just paraphrasing. Use multiple sources as the basis for your definition, extracting the common concepts from across them. Do not use footnote references if the source is not a dated source! (See References below.)

Examples for comprehension:

Provide simple examples if it helps clarify understanding. Add your examples either as parenthetical notes after a given, tricky concept itself, or give fully-phrased examples at the end of the definition.

Cross-linking:

If you're definition uses a term elsewhere in the glossary repo, surround it with double straight brackets, [[term]], so editors know where to bridge links later.

Related terms

If there are multiple, strongly-related terms but with slight differences in meaning (e.g. see term, user journey, in glossary):

1. determine which is the most universal and use that as the main term to define, then
2. use a numbered list to sub-define the other more specific terms under universal definition.

(Keep in mind this is the kind of thing that can be challenged and debated with Issues.)

No buzzwords or jargon

Avoid suggesting the addition of “buzzy” terms, like engagement, storytelling, and the tiresome like. Such terms are either not easily agreed upon or too easily abused to the point of having no meaning at all. If you're not sure about a term, ask yourself if a definition can be given that most everyone would agree on across various UX fields. If you're pigeon-holing your definition into the context of one discipline or schema, for example, it's not a good term.

(Keep in mind this is the kind of thing that can be challenged and debated with Issues.)

Formatting

We'll use Markdown for formatting article drafts here in the repository because GitHub favors it and it transfers easily to the production CMS when the time comes. See GitHub's Markdown Cheatsheet for the Markdown that GitHub actually supports.

You do not have to learn all that, in fact, much of what is there won't be required. But it does give you the syntax to use in cases where you will use Markdown syntax in definitions. This could include:

• section headers
• bulleted or numbered lists
• bold and italic text
• links
• images

Regarding images, see Figures section below.

References

Every definition should have at least 2 reference from some respectable sources! We're not inventing definitions; we're building on the knowledge that came before while shaping to adapt to the future. We require 2 sources so not to just reiterating what someone else wrote, rather we're synthesizing the ideas of multiple people.

Do not use a source as a reference if the source has no date of publication! Dates are important for showing the value of the source relative to time. For purposes of this project, if the source is not dated, it's considered dubious and unusable, regardless of how accurate it may be and from who.

It's fine to use the ideas discussed in your source information as part of your definition. But do not plagiarize, or paraphrase so similarly as to be obviously lazy. And do not cite the work as part of the definition copy. For example, don't do something like this:

John Von Hämmer at JVH Media Inc. says, "dada, dada, bla-bla". So that's the end of it then. We've got nothing more to say on the matter.

There's nothing wrong with inline citations, generally speaking, but in this case we want definition copy free of such verbiage so it reads clear and easy. (And, there's likely more to say on the matter regardless of what Mr. Hämmer says.)

References should be added as footnotes, with footnote numbers added to the ends of sentences for which source information is most applicable. Add the numbers using syntax like this: [^1]. Then, provide the reference at the bottom of the article in numbered list fashion. We won't be keeping footnotes and a comprehensive bibliography (e.g. at the back of the entire glossary), so structure your references in a more bibliography-like format:

1. Richards, S., [_Write user stories to share responsibility for content_](https://2016.agilecontentconf.com/richards), Agile Content Conference, 2016. Accessed 24 February 2016.

That Markdown makes the reference look like:

1. Richards, S., Write user stories to share responsibility for content, Agile Content Conference, 2016. Accessed 24 February 2016.

Figures

Figures are encouraged when they enhance understanding of the primary meaning of the term. But they are not required in every case, and some definitions may be better without them.

As a contributing author to a definition, you are not required to worry about all the Markdown formatting. Editors will be responsible for cleaning that up. But if expect a figure to be used in your work, you need to provide the initial image URL and associated microcopy (caption, alt text...). The manner you do this depends on what stage your contributing.

If you're writing the initial definition for a term (a blank slate), then you must add the information directly to the draft. Don't worry about marking it up correctly, just include this in the draft flow where the image should go (editors will clean it up later):

Figure url: url here
Caption: caption text here
Alt: alt text here

However, if you're intention is to provide a missing image for a definition that has already been drafted, or to provide one you think is better than what might exist, you must 'challenge the definition' using the associated issue. Read the doc on Using issues for collaboration, notably the section on challenging definitions.

The target working state for a definition draft

A definition is considered in a working (production-grade) state when the draft file includes:

• title (the term itself)
• summary (for production use)
• full definition that's constructed reasonably well (see Construction section earlier)
• figure (if applicable; see Figures section earlier)
• cross-reference links to other mentioned terms (if applicable)
• correctly formatted footnote references (at least 2)

It must also have all required metadata information added in the Glossary terms register for safe keeping when it comes time for production. (FYI: there's an issue label for flagging definitions that lack metadata.)