Skip to content

Add What is a Glossary? explanation #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
degville merged 26 commits into from
Jul 25, 2025
Merged

Add What is a Glossary? explanation #199

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
9dc677d
Add draft explanation What is a Glossary?
bruce-esrig Mar 28, 2025
2a2b0d7
Corrected errors ... note that there's no glossary (yet?), so the ter…
bruce-esrig Mar 28, 2025
91eca0f
Merge branch 'canonical:main' into gloss-explain
bruce-esrig Mar 28, 2025
d08fbc5
Caught up w oda/main. Fixed typo in links for authors. Updated custom…
bruce-esrig Mar 28, 2025
cecd913
Added mini-glossaries. Removed some excess headings.
bruce-esrig Apr 2, 2025
2e93826
Deleting another two excess headings.
bruce-esrig Apr 2, 2025
4ce203b
Add appendices for mechanics and locally-defined terms. rST and MyST …
bruce-esrig Apr 3, 2025
73d27c3
Merge branch 'canonical:main' into gloss-explain
bruce-esrig Apr 4, 2025
e986bac
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
79c5382
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
f9c4ded
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
5d08c72
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
0b7f809
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
dc1494c
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
d197584
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
26dbeaf
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
6d67e4b
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
fbaecec
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
6f650a3
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
2d726e5
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
9af28da
Update website/docs/explanation/glossary_what.md
bruce-esrig Apr 15, 2025
d7ecba1
Use 4-space indentation for quoted markup. Explain glossary entry < d…
bruce-esrig Apr 16, 2025
f913bce
Merge branch 'canonical:main' into gloss-explain
bruce-esrig Apr 20, 2025
0ab2e44
Merge branch 'main' into gloss-explain
s-makin Apr 22, 2025
e850bcb
Merge branch 'canonical:main' into gloss-explain
bruce-esrig Apr 29, 2025
578cc1b
Merge branch 'canonical:main' into gloss-explain
bruce-esrig May 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions website/.custom_wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,30 @@ AngularJS
AsciiDoc
backends
bootable
Center
Ceph
CLA
Coursera
Ctrl
DDNS
DIT
DITA
DNS
docsacademy
DTLS
FC
Fiber
freesewing
GnuTLS
golang
Hackmamba
howto
https
IoT
JIRA
KDE
LaTeX
LDAP
lifecycle
MAAS
MDX
Expand All @@ -27,7 +38,10 @@ Multipass
Netplan
ODA
onboarding
OpenLDAP
OpenStack
organize
prized
PRs
rebase
rebasing
Expand All @@ -36,5 +50,9 @@ repos
RST
scalable
Snapcraft
specialized
specializes
SSL
TLS
WSL

86 changes: 86 additions & 0 deletions website/docs/explanation/glossary_what.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# What is a glossary?

## Purpose

This topic will provide background information on glossaries:
* What they are for
* How they are structured
* What advanced features are available

## What is a glossary?

A *glossary* gives the meanings of *terms* in a work or domain.
It is presented as a list of terms in alphabetic order, each with a *gloss* that explains the term.

Each explanation gives the reader enough understanding to become familiar, and perhaps even comfortable, with the term.

Simplicity is prized. As a rule of thumb, a glossary entry should make the reader one step more comfortable with the term.

## Structural features

### Simple definition

A definition is a statement of fact that conveys the meaning of a term.
Copy link
Collaborator

@s-makin s-makin Apr 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A definition is a statement of fact that conveys the meaning of a term.
A definition, or *gloss*, is a statement of fact that conveys the meaning of a term.

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A gloss is more than a definition since it can include all kinds of extra features (See also, etc.).

Second, I was hiding a question about terms with multiple meanings. Is the gloss everything after the entry, or is a gloss what is written about an individual numbered sense? I'm inclined to define gloss as the smaller of the two, so that each numbered sense has its own gloss.

Copy link
Collaborator

@s-makin s-makin Apr 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In that case, should we redefine the header "Structure" as "Structure of the gloss" or similar?

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about ... (putting the content here till my git fix is in) ...

Structure of a gloss

This section describes a gloss that explains a single sense of a term.

If a term has multiple senses, each sense has its own gloss. In that case, the glosses under the term are numbered. The order of the glosses should be instructive, with the most basic or common senses presented first.

A definition that consists of a simple phrase or sentence may be all the explanation that is needed.

**core** <br />
Copy link
Collaborator

@s-makin s-makin Mar 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all these examples of glossary features, I'd recommend creating a mini glossary environment for each of them so they render on the page as they would in a full glossary. The syntax should be something like this for MyST:

:::{glossary}
Term goes here
: Term definition/gloss goes here
:::

(see the MyST docs for a full description)

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's really nifty!
If you'll pardon the rudimentary question ... does the Sphinx parser recognize the various markdown paradigms as it encounters them, or does it need additional cues? Before you said this, I was implicitly assuming File extension == > markup language.

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update:
MyST recommends relying on Conda.
https://myst-parser.readthedocs.io/en/v0.16.1/sphinx/intro.html
I have Ubuntu running on ARM (my MacBook).
However, Conda doesn't support ARM.
conda/conda#13951

Support for MyST is experimental on ARM.
Wondering whether to try the experimental path that Mara Lampert's blog mentions.
https://biapol.github.io/blog/mara_lampert/getting_started_with_miniforge_and_python/readme.html

Previous remarks:
I'm suspecting that MyST needs to be installed. Would that be added to the "Set up Sphinx" topic, or built into Makefile?
The symptom is that when I add myst_enable_extensions = [ "colon_fence" ] to conf.py, the build breaks.
Even without installing MyST, Sphinx does accept this: adding "myst_parser" to extensions in conf.py.

Copy link
Collaborator

@s-makin s-makin Apr 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just checked the conf file and it looks like MyST should just work automatically - myst parser is included as part of the canonical sphinx extension (which is enabled). Have you tried running a clean build? Sometimes it doesn't just enable an extension and you have to rebuild the whole thing from scratch. (make clean and then make install should see everything set up correctly, then make run should work).

If running a clean build doesn't work, let me know and I'll do some more digging.

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alas, a clean build does not suffice. I restored conf.py and ran make clean; make install; make run. The local preview of my latest revision of the glossary_what.md file shows

:term:`NFS`

rather than processing the term reference.

I put some notes in my previous comment about difficulties installing MyST on ARM.

Copy link
Collaborator

@s-makin s-makin Apr 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I found the source of the problems! I've added suggestions for all the instances I could find (I may have missed one or two though)

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, Sally! I was a bit confused about which markdown languages work where. I now think that MyST works on top of MD (in .md files) but RST is separate (in .rst files).

Copy link
Collaborator

@s-makin s-makin Apr 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's exactly right :) MyST is just an extension of standard markdown that adds a lot of the functionality you get with rST. All the Canonical GitHub projects that use Markdown will be using MyST to some extent (probably) in their .md files, otherwise they'll use rST. You can mix-and-match markdown and rST files in the same project (sphinx will allow you to work with both), but each individual file has to be one or the other.

The working memory of a computer.

When a formal style is used, the item being defined is omitted from the beginning of the explanation.

### Abbreviation

If the term is an abbreviation, the gloss starts with its expansion. The abbreviation is explained briefly after its expansion.

**DNS** <br />
**Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20).

### Abbreviation (conversational)

A more conversational style is sometimes used, especially when the expansion of an abbreviation can be read as the subject of the gloss.

**FC** <br />
Fiber Channel (FC) is a storage networking protocol used for low-latency communication between a storage device and a node
in a Storage Area Network (SAN).

In this definition of FC, expansions are followed by abbreviations as is customary in running text.
This is a good way to handle abbreviations such as FC and SAN that are comparatively specialized.

### Cross-references

Cross-references help readers navigate among related terms.

#### A casual mention of another term

If the gloss for a term discusses a second term, the second term should be linked.

<!-- {term}`DNS` replaced by *DNS* -->
<!-- other terms: LDAP, SSL, TLS, DTLS -->


**DDNS** <br />
**Dynamic Domain Name System**. A service that automatically updates (term-ref) *DNS* records when the underlying IP address changes (aka, dynamic IP).
Copy link
Collaborator

@s-makin s-makin Mar 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is where I think using mini-glossaries for these examples would really shine - then you can cross-reference between them as if they really were glossary entries :)

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see how mini-glossaries can be helpful. I created some along the way, and then pooled a few glossary entries at the bottom in a section titled "Appendix 2". Those are the terms that are referenced but are not themselves needed as examples.

Copy link
Contributor Author

@bruce-esrig bruce-esrig Apr 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also created "Appendix 1" for code examples. Instructionally, I think it's clearer to have them collected. As how-to material, it might need to be split out, but that depends on how orthodox we're being about factoring instructional information about glossaries.

Copy link
Collaborator

@s-makin s-makin Apr 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all of this can reasonably be counted as "explanation" rather than "how-to" - having illustrative examples is totally fine in an explanation page :)


#### A term that provides depth or broader context

When a concept that provides depth or broader context is used in a gloss, it can be linked using "See".

**DIT** <br />
**Directory Information Tree**. In directory services (See (term-ref) *LDAP*), a hierarchical tree-like structure used to organize and store information.

#### A related topic

A collection of related topics can be provided at the end of the gloss.

**GnuTLS** <br />
**GNU’s Not Unix Transport Layer Security**. A GNU software package that secures data in transit by implementing the (term-ref) *SSL*, (term-ref) *TLS*, and (term-ref) *DTLS* protocols.

Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP.

## Advanced features

In this treatment, the features considered basic are those focused on meaning.
Copy link
Collaborator

@s-makin s-makin Apr 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence doesn't really add much, since we didn't describe the previous content as basic (and we probably don't need to). I think we can safely remove this sentence without harming the rest of the content :)


There is an additional realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest.

Advanced features can be introduced in glossaries by imitating the features of entries in authoritative dictionaries.
1 change: 1 addition & 0 deletions website/docs/explanation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,6 @@
:glob:
:maxdepth: 1

What is a glossary <glossary_what>
About the Academy <about>
```
2 changes: 1 addition & 1 deletion website/library/reference/links-for-technical-writers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
- [Google Style Guides](https://google.github.io/styleguide/): guides on style for languages from AngularJS to Vim script.
- [Diátaxis](https://diataxis.fr/): a systematic approach to technical documentation authoring.
- [Introduction to DITA](https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/introduction-to-dita.html#introduction-to-dita): an open standard and architecture for technical information.
- [Technical Writing Resources](https://developers.google.com/tech-writing/resources): resources and style guides from Google for developerss.
- [Technical Writing Resources](https://developers.google.com/tech-writing/resources): resources and style guides from Google for developers.
- [What is a Technical Writer Style Guide? With Examples](https://document360.com/blog/technical-writer-style-guide/): guide with style examples from Document360.

## Frameworks
Expand Down