canonical / canonical/ubuntu-server-documentation
Update: building up the new glossary
- Dominant language
- Makefile
- Stars
- 88
- Forks
- 159
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 5
Description
## The problem
Now that [we have a glossary](https://github.com/canonical/ubuntu-server-documentation/pull/124), we need to begin defining the terms.
## What is needed
Since the glossary was based on the spelling exceptions list I have made a first pass to clear out the spelling exceptions, duplicates, and plural items. However, there are still plenty of terms that don't belong there, and all terms need to be defined. Some terms/acryonyms may have more than one definition.
- Each *valid* term in the glossary needs a clear definition.
- Invalid terms need to be removed.
- Once a term has a definition, it needs to be referencedlinked in any pages that use that term (at the first place on each page that the term appears).
**What's a valid term?**
- Acronyms
- Product or package names (definition of the spelling and capitalization should come from the official product documentation)
- Technical terms/jargon
**What's an invalid term?**
- Code elements/terms that only appear in code blocks without a corresponding textual definition
- A plural of a term that's already been defined
- A duplicate of a term with alternative spelling
- Terms that *only* appear in the glossary page
## Suggestions
I don't recommend trying to tackle the entire list in one PR, it's very long and would be a lot for one person to do alone! Pick a subset of terms you want to define (I suggest no more than 5-10 in one go).
- For each term, search in the [rendered documentation](https://documentation.ubuntu.com/server/) to see which page(s) it appears in - you'll want to make a note of those for later.
- If it's an invalid term, it can be deleted from the glossary list.
- If it only has a single definition/meaning, include the definition in the glossary - it's fine to pick this up from the documentation. Feel free to link to other supporting material (such as manual pages or official package documentation) as you see fit.
- It it has more than one meaning, make sure to include all possible definitions.
- It would be great to also refer to the section/topic the term relates to (e.g. ACLs are related to security, but also pops up in the OpenLDAP and Kerberos content). This will help in the future, as we may want to provide section-specific glossaries, or organise the glossary into sections.
- Finally, after you have defined the term, include a reference to the glossary entry on *each page* where the term appears, using the MyST syntax:
```
{term}`glossary term to link to`
```
The term inside the backticks needs to match the glossary term *exactly*. But, if you want to point to a term with a different link text, you can use the following syntax instead:
```
{term}`Acess Control Lists `
```
Where in this example, "Acess Control Lists" is the link text shown to the user, and ACL is the term as it appears in the glossary.
- The terms only need to be linked to the glossary the first time they appear on each page (i.e., you don't need to link every appearance).
### Related to
- https://github.com/canonical/ubuntu-server-documentation/issues/5
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by selecting a small subset of 5-10 terms and searching the rendered Ubuntu Server documentation to find where each appears. Check each term against the validity rules, define valid terms in the glossary, remove invalid ones, and add a first-use MyST glossary link on every relevant page.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100