-
Notifications
You must be signed in to change notification settings - Fork 0
Using the definition template
Use this template to start a new glossary definition file. You do not have to "finish" a definition (utopia is always a dangling carrot). You don't even have to start the initial copy. Creating the initial draft file, if it's missing, is enough. Or you can start the definition copy and leave some work for others to do. Whatever. This will likely be necessary anyway for elements like definition examples, references, and figures. Remember, this is a collaborative project.
This template and explanatory information will be updated whenever improvements are made to it.
On this page:
- Using the template
- File change explanations
- Issue label updates
New definition files should only be created according to collaboration protocols. Otherwise communication breaks down and people starting working rogue. That's not good. The protocol for creating new definition files is a two-step process.
An issue must exist for each primary glossary term before its definition file is started. Search the Issues list to find out if a given term issue exists. Term issues are distinctive by their titling convention, term: Term name.
Chances are the issue does already exist, unless you're intention is to propose a new glossary term, in which case you should not be starting a draft file yet (see protocols in Using issues and Using issue labels).
If a primary term issue does exist but there's no draft file started, the issue should have 2 labels on it: term primary and definition file needs created. That's your green light to go ahead an create the file using the instructions in the next section.
The definition-template.md file is in the root of the repository. When you clone the master repository, which you should have done before this point, you'll have the template in your local directory.
When you're set up locally and have verified the green light for creating a definition file, proceed as follows:
- Duplicate the template file in your local clone folder. (Your operating system probably has a right-click menu option for this.)
- Rename the duplicated file to reflect the term you're starting the file for. Do not change the file extension. Use hyphens in place of spaces, all lowercase. (E.g.
pair-writing.md) - Important! Sync (down) the master repository to your clone. (Ensures you have collaborator changes first. )
- Commit/push (up) your local changes to the master repo.
At this point the new blank file is added to master. All collaborators can see it. You now have a choice to make:
- continue with writing draft definition copy, or
- leave the new file alone and come back to it later (or not).
Leaving it alone means anyone else can start working on it by adding the definition claimed (7 days) label on the associated issue, then proceeding to get busy. The label is part of our collaboration protocols, as described in using issue labels. It prevents collaborators from stepping on each others' toes.
If you want to start the initial definition copy, then you need to add the definition claimed (7 days) label yourself to the term's issue. This tells everyone to leave that file alone until your 7 days is over. See additional protocols for issues at the end of this page for when you've made file copy changes.
Attention: the sole act of adding a new definition file to the repository does not count for getting author credit on the file. To earn your name on the file as a contributing author, you must actually contribute to the definition copy to a measurable degree. This measure is first determined by what you initially write in a new file, then later by finishing definition files, then finally by whatever approved challenges and corresponding revisions you make in course of collaboration using issues and using issue labels.
Don't be put off by all the HTML markup you see in the template. You don't have to touch it, nor do you have to add any yourself. All of the markup is already in place. If any changes to template HTML are needed, the technical editors will do it and update any past definition files too. The HTML is necessary or we can't add important accessibility, metadata, and semantic schema attributes, which we will be adding over time. Markdown alone is incapable of supporting such attributes.
But we can use basic Markdown in the general paragraphs (see the Glossary Markdown cheatsheet, if needed), which are what you will be writing. And you can easily add the important text elements in the "Front Matter" at top of each file. Neither of which requires knowledge of HTML or touching it at all. Just be careful not to move or delete the HTML that already exists, unless instructed to.
At the top of the template is the "front matter", written in YAML, a human-friendly data serialization language. The front matter is a critical part of the templating system used by GitHub Pages and Jekyll to make the repository function as a flat-file backend to the production frontend.
Front matter is also great for adding/editing metadata, microcopy, and similar so you don't have to wade through HTML markup. Instead, you add your text strings and microcopy at the top of the page where it's easy to see and read. This also helps prevent accidental edits of the HTML.
The front matter begins and ends with a line of 3 hyphens. Never remove those. Between those lines are a series of variables (e.g. published, layout, issue_id, etc). This is what you see by default:
---
published: false
layout: definition
issue_id:
file_name:
title:
description:
summary:
tags:
contributors:
- name: First Last
affiliation: Entity Name
url: https://content-strategy-forum.github.io/csf-glossary/{{file_name}}.html
figname: placeholder
figalt: Placeholder
figcaption: Candidate for a custom figure?
---
The top-to-bottom order of the variables doesn't matter, but we have them organized in a semi-logical manner for technical editing reasons, so it's best if you don't go mixing the order around to stay consistent. The blank lines between variables also don't matter, but it's just easier to see the variables like this than when they are all pressed together, especially after you start adding the content values.
The following table explains all the front matter variables and which ones you are responsible for.
| Variable | Do you add/edit? | What is it (or for)? | Rules |
| --- | --- | --- |
| published | No | defines whether the file is published or not | true/false |
| layout | No | defines what HTML template the web page should use | fixed value (definition) |
| issue_id | Yes | the ID of the issue for the file, which must exist before file is started | number |
| file_name | Yes | the file name for the Markdown document; parses to "Source file" link in production site footer | a lowercase, hyphenated slug (e.g. pair-writing) |
| title | Yes | human-friendly version of term; parses to the human-readable title of definition page | sentence-case (e.g. Pair writing) |
| description | Yes | parses to the HTML head meta-description, etc | 160 characters max |
| summary | Yes | parses to the definition summary under the page title | single para; ~50 words, give or take |
| tags | No, not yet | will provide a means for filtering the glossary; but this is a future development | single, or comma-separated |
| contributors | Yes | values parse into the respective author/affiliation markup | your names and URL |
| figure | No | values parse into the respective figure markup, when one is appropriate | file name, alt text, caption |
Additional notes, where appropriate, are provided for each variable in the following sections.
The published variable is for chief editor use only. The file is not published by default and remains unpublished until it works through a collaborative state of being sufficiently ready for prime-time. To be ready, a file must:
- have all needed content elements as described on this page,
- pass the technical editors' checklist, then
- be reviewed by the chief editor
The chief editor then changes the variable value to true, add term to the index.md, and commits changes to publish the work.
The description value should be a hyper-concise paragraph not more than a 160 characters in total length. The Mozilla Developer Network [recommends 155 characters(https://moz.com/learn/seo/meta-description) to avoid any truncation. The description variable is used in the meta description tag, search engine results, and potentially in the title attribute value of linked terms in the glossary index.
An example description with 130 characters, well within the ideal length:
description: A collaborative writing process that matches a knowledge expert with a copywriter or editor to produce a piece of written content.
Another example with 156 characters, also ideal (remember, 160 chars max):
description: Short strings of text (1-5 words) used in digital interfaces to guide exploration, text input, personalization, and the like. Not the same as microcopy.
The summary value should be a single paragraph around 50 words, give or take. The summary should be slightly more explanatory than the description above, but much less detailed than the full definition. Do not mention examples, figures, or synonymous terms in the summary. Nor should there be any inline footnote numbers added here. Do not use Markdown formatting on any of the copy, as formatting is handled in CSS.
Skip this one for now. Leave the variable value blank. We'll come back to grouping and tagging terms later after exploring it a bit in Term categories and tags. This information will update when functionally ready.
But, when adding tags, add a single tag like this:
tags: tag
And add multiple tags like this:
tags: [tag1, tag2, tag3, etc]
The contributors variable requires 3 pieces of information for each contributing writer: name, affiliation, and URL of affiliation. Placeholder values exist in the default variable:
contributors:
- who: First Last
affiliation: Entity Name
affiliation-url: https://content-strategy-forum.github.io/csf-glossary/{{file_name}}.html
Contributors add their own details in the order contributions are made to the file. You only add the information for yourself if you provide any copy contribution to the definition. (Just creating the file doesn't count for author credit.)
So, if you were "Pat Stewart" working at "Stewart Agency", which had a website at "https://pat-stewart.agency", you would change the default values to:
contributors:
- who: Pat Stewart
affiliation: Stewart Agency
affiliation-url: https://pat-stewart.agency
If Tracy Connors was the second contributor to the definition, they would add another three lines for their details immediately under the previous entry:
contributors:
- who: Pat Stewart
affiliation: Stewart Agency
affiliation-url: https://pat-stewart.agency
- who: Tracy Connors
affiliation: University of Twente, Department of Marketing and Communications
affiliation-url: https://www.utwente.nl/en/mc/
Note the indentation of each line, and particularly the first line for each respective contributor, which requires the preceding hyphen to parse each person's data correctly. To make it easy, each additional contributor can copy the three lines of the preceding contributor, paste the lines underneath, and edit them accordingly.
The 3 "fig" variables are for technical editor use only. The variables have placeholder values by default. Just leave them in place. They fill the variable dependencies in the figure markup:
<!-- FIGURE (REMOVE CODE IF NOT NEEDED) -->
<figure><img alt="{{page.figalt}}" src="{% include domain.html %}/csf-glossary/assets/images/{{page.figname}}.png">
<figcaption>{{page.figcaption}}</figcaption>
</figure>
-
{% assign counter = 1 %}
{% for item in include.ref %}
- {{item.name}}{{counter}} {% assign counter = counter | plus:1 %} {% endfor %}
-
{% assign counter = 1 %}
{% for item in include.ref %}
- {{counter}}{{item.affiliation}} {% assign counter = counter | plus:1 %} {% endfor %}
See the Figure section below for more explanation about handling figures.
See this article in Nature, as an example of the author/affiliation structure we're aiming for.
Add your name and affiliation only. The name order is dictated by the order contributions are made to the draft. If you're starting the draft and the definition, your name is first in the contributions list. The next contributor is second, and so on.
Do not add your name and affiliation if you do not contribute any copy to the definition. Just creating a blank draft file does not count for getting author credit.
To add your name, replace First Last in the following line with your own first and last name. Be careful not to remove any of the surrounding HTML markup:
<li>First Last<sup>1</sup></li>
In the associated affiliation line, replace https://domain.tld with your affiliation website link, and replace Affiliation Name with the name of your affiliation:
<li><sup>1</sup> <a href="https://domain.tld">Affiliation Name</a></li>
Use the most prestigious affiliation you can: 1) association, 2) company, 3) university, 4) personal website...). NO EMAILS OR SOCIAL MEDIA PROFILE LINKS.
The body of the definition should be written with a particular linear order:
- Primary term explanation.
- [If possible] One or two real-world examples of term topic exhibited (references should be provided).
- [If appropriate] A figure (diagram, chart, model...) that corresponds with the general definition or one of the examples. A figure should only be added if appropriate for the given definition. Some definitions won't need one.
- [If appropriate] Explanation of synonymous terms (i.e. the related terms in the index that redirect to the current primary definition); subtle distinctions or conditions of use versus primary term, their histories/contexts of use, and/or whatever else might be relevant and educational.
Not every definition has to have every element in the structure, but elements should be in this order when available and appropriate.
The HTML <sup>...</sup> are necessary for adding inline reference numbers for footnots, but the numbers you see in the following examples are arbitrary. You would change footnotes as copywriting requires. See Footnotes section later for full details about required sources and using footnotes.
The opening paragraph(s) of the definition article should focus on the primary term being defined. The placeholder copy in the definition also explains this, and is denoted by an HTML tag
<!-- PRIMARY PARAGRAPH(S) OF DEFINITION -->
First para for primary term's explanation. Add the footnote reference number
on the most applicable sentence related to referenced source.<sup class="ref">1</sup> Yadda yadda.
Or simply use the reference number at the end of a full paragraph, if appropriate.<sup class="ref">2</sup>
Use multiple paragraphs, if needed.
Edit the copy accordingly, or leave all the placeholder content alone if you don't intend to make any changes this time around.
When used, figures should be in relation to the primary part of the definition, but preceded by at least the opening paragraph. This is explained in the template's placeholder copy too:
Somewhere in relation to the primary explanation might be a figure, but inserted after the opening paragraph somewhere.
<!-- FIGURE (REMOVE CODE IF NOT NEEDED) -->
<figure><img alt="{{page.figalt}}" src="{% include domain.html %}/csf-glossary/assets/images/{{page.figname}}.png">
<figcaption>{{page.figcaption}}</figcaption>
</figure>
However, figures are a special situation in the collaborative workflow. Repo managers have the responsibility to create custom figures for all glossary definitions, if/when a figure is needed at all. At that time, managers will also add the necessary figure Front Matter values too. You do not have to touch the figure markup at all.
We follow this process for several reasons:
- It eliminates having to find figures that are public domain, or that we must get rights of use for; and they would have to be one or the other otherwise. We skip that seek-and-ask step by creating our own, and thus all figures adopt the licensing rights of the glossary automatically. (See README.)
- It gives a more unbiased impression to readers, as opposed to images sourced by a given brand or individual. The glossary is not meant to be a promotional vehicle for brands.
- It enables normalizing the design pattern across all figures in the glossary. This removes the visual hodge-podge affect that otherwise comes from plucking figures from many different sources.
- It simplifies the collaborative process around figure decisions, and keep issues updated in the process.
Some definitions can benefit from figures, and figure concept ideas are easily imagined. Others definitions don't need figures at all, or at least they are not critical to understanding (though they could be a nice finishing touch).
You can help make the initial call about whether the definition could benefit from a figure or not. If you do think a figure is appropriate, then:
- leave the figure markup in place,
- move to the synonymous terms and footnotes areas, and
- address the figure in the term's issue as explained in the last section of this page.
If you think a figure is not needed, then remove the entire placeholder block of text and markup as shown above, and remove the 3 placeholder values from related variables in the Front Matter.
Following the primary definition and figure (if used) should be one or more real-world examples (as opposed to theoretical). Ideally there is one paragraph of varying length for each example provided, and each example should have at least one reference, or it's probably not a good example to use.
<!-- EXAMPLE(S) -->
Use a new paragraph for each real-world example.<sup class="ref">4</sup>
Each example should reference a source, unless theoretical.<sup class="ref">5</sup>
Similar terms refers to the terms that are similar in meaning to the primary term, but which did not win out (via collaborator debate) as having the primary spot in the glossary. In this case, the terms are still added in the index as secondary terms that redirect to the primary definition entry.
To give those terms some lip service, without adding redundant definition files in the glossary, we explain them a bit in this final region of the primary term's body. This part would obviously require some effort researching and reading about related terms, in which case you should provide a footnote reference for each related term you talk about.
Develop this section according to the following "ifs":
- If there are no synonymous terms, skip this part of the definition entirely.
- If there are only one or two related terms and there's not much to say about them, then say what you can in a single paragraph for both, and be sure to add reference numbers to the appropriate sentences.
- If there are 3 or more and/or a bit more can be said about each one, use a separate paragraph for each one, adding the reference numbers at the end of each paragraph, respectively.
Note the placeholder copy is also explanatory:
<!-- SIMILAR TERMS EXPLAINED, IF ANY -->
Use a new paragraph for each mention of a similar term. Similar terms are what we include in the glossary index as _secondary_ entries that redirect to the primary entry. So don't include a "similar" term if it's not synonymous with the primary term, or at least close. Any differences for close terms should be explained. Similar terms mentioned must have at least one (different) source reference each.<sup class="ref">6</sup>
If no similar terms exist to mention, remove the above default block of text from the file, including the HTML comment.
Every definition must have at least 2 footnote references to be production ready.
The more references the better per definition, and especially for the primary region. But their minimum application to the definition should be gauged as follows:
- 2 references applied to primary region
- 1 reference for each real-world example
- 1 reference for each synonymous term explained
Real-life examples: It's expected you'll have only 1 reference for each real-life example, since such examples are typically unique instances.
Synonymous terms: It's quite feasible that multiple references exist for a given term. In that case, judge it this way: 2 refs are better than 1, but 4 refs are probably too many. Pick the best sources.
When selecting references to use, pick the most reputable and recognized sources from what's available. Sources from standards bodies and industry associations are better than something from an ad-laden blog article in the dark web, for example.
Also, regardless of what the source is or how reputable the author, if the source has no publish date on it, it cannot be used. This rule exists because without a publish date, there's no way to gauge the information's temporal relevance.
References will be handled using regular HTML, which is necessary for adding semantic attributes. The inline reference numbers follow this notation, <sup class="ref">n</sup>. You only have to change n, which is the number in sequence as you add sources.
The footnotes themselves begin with this notation, <sup>n</sup>, where n matches the inline number, followed by the source reference information.
Add the inline numbers to the most applicable sentences in your copy for which the source information applies. If source information applies the entire paragraph, then add the number to the end of the last sentence.
We use a version of the Oxford Referencing System. We say "version" because unlike a true ORS, which uses both footnotes on a page and a complete bibliography at the end of the work, we're only going to use the footnotes per definition, no glossary-wide bibliography.
We also have to settle on a given format, because even within Oxford there are different ways to construct a reference. We think this Oxford Referencing resource is easy enough to use. Give your attention to the sections Part 2 Footnotes and Repeat citations.
When a resource is available online — the actual source, not just the container (e.g. book site) — put the source URL on the title of article and make it italic instead of wrapped in single-quotes. This is likely common in our case for web articles, as accounted for in the template:
<li><sup>1</sup>
F. Last, _[Title of article](url)_, Name of site, Blog, YYYY, (accessed Month DD, YYYY).
</li>
Sometimes a website has a name for its blog column too (e.g. 'The Diviner'). In that case, use:
<li><sup>1</sup>
F. Last, _[Title of article](url)_, Name of site, Name of blog, DD Month YYYY, (accessed Month DD, YYYY).
</li>
When you finally commit your new file to the master repository, make sure you update the term's issue with the appropriate information and status labels. How you need to do that depends on how for you went with the initial draft.
If you feel you completed the definition as described in this page, including the provision of needed references, then update the issue with the editor review needed label. And you may need remove previous labels that are no longer relevant, such as the definition claimed (7 days) label if you had been added.
Alternatively, if you didn't finish the initial draft, make a comment in the issue about how far you think you got and what still needs done, then add the definition needs finished label. Again, removing any previous labels that would now be irrelevant.
Finally, if you think the definition could benefit from a figure, as described earlier, make a comment about that too and add the discussion needed label. This would be in addition to either of the above situations.
README | Glossary index | Terms register (temporary)