78 lines
4.3 KiB
Markdown
78 lines
4.3 KiB
Markdown
---
|
|
name: corp-v1-glossary
|
|
description: Govern shared terms in Corp v1 project documentation.
|
|
version: 1.0.0
|
|
author: Lego (RootAtSkic), Hermes Agent
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
metadata:
|
|
hermes:
|
|
tags: [corp-v1, glossary, terminology, documentation]
|
|
related_skills: [documentation-docusaurus]
|
|
---
|
|
|
|
# Corp v1 Glossary
|
|
|
|
This skill governs project terminology. It keeps term definitions out of architecture, scope, delivery, and other domain pages while preserving links from those pages to one authoritative project Glossary.
|
|
|
|
## When to Use
|
|
|
|
Use this skill when:
|
|
|
|
- a Corp v1 page explains what a domain or technical term means;
|
|
- the same term may appear in more than one documentation area;
|
|
- reviewers disagree about terminology or classification;
|
|
- creating or restructuring a project's top-level Glossary area;
|
|
- adding, changing, deprecating, or linking a project term.
|
|
|
|
Do not use it for ordinary narrative, requirements, architecture decisions, procedures, or API reference that does not define reusable terminology.
|
|
|
|
## Documentation Contract
|
|
|
|
Every Corp v1 project documentation site has **Glossary** as its final top-level menu item with a dedicated sidebar. The minimum sidebar begins with `Terms`; projects may add alphabetical term pages beneath it when the registry becomes difficult to scan.
|
|
|
|
A glossary entry records:
|
|
|
|
```text
|
|
Term | definition | scope | status | aliases | related terms | authoritative links
|
|
```
|
|
|
|
Rules:
|
|
|
|
1. Define a term once in Glossary and link to it from domain pages.
|
|
2. Keep the definition concise and project-specific; do not paste generic encyclopedia material.
|
|
3. State the operational distinction the reader needs. For example, distinguish a deployable C4 container from a code component.
|
|
4. Preserve domain evidence in its owning area. Glossary explains the term; Architecture owns architecture facts and decisions, Scope owns product definitions, and Delivery owns implementation procedures.
|
|
5. Use stable lowercase anchors or slugs and link every first material use where Docusaurus permits.
|
|
6. Record aliases and deprecated wording rather than silently deleting terms that remain in historical records.
|
|
7. Mark uncertain or proposed definitions as `Proposed`; only verified/approved definitions are `Adopted`.
|
|
8. Avoid circular definitions and definitions that rely on unexplained project jargon.
|
|
|
|
## Procedure
|
|
|
|
1. Identify the reusable term and the exact sentence that currently explains it. Completion: the candidate is terminology rather than domain evidence or procedure.
|
|
2. Search the project's Glossary and domain pages for existing definitions or aliases. Completion: duplicates and contradictions are listed.
|
|
3. Add or update one canonical Glossary entry with scope, status, aliases, related terms, and authoritative links. Completion: one stable term anchor or page owns the definition.
|
|
4. Replace duplicated explanatory prose with a concise contextual statement and Glossary link. Completion: domain pages retain only facts needed for that page.
|
|
5. Validate dedicated navigation, links, Docusaurus build, and deployed rendering using the project's documentation skill. Completion: the Glossary is last in top-level navigation and every changed link resolves.
|
|
6. Publish through the project's review and verification workflow. Completion: immutable source readback and deployed-page evidence confirm the term and links.
|
|
|
|
## Pitfalls
|
|
|
|
1. Turning Glossary into a catch-all reference manual.
|
|
2. Moving architecture evidence or decisions out of Architecture.
|
|
3. Treating a library as a deployable container because both use the word “package.”
|
|
4. Duplicating the same definition across several pages.
|
|
5. Adding generic definitions that do not clarify project usage.
|
|
6. Renaming historical terminology without aliases or deprecation notes.
|
|
7. Placing Glossary anywhere except last in top-level navigation.
|
|
|
|
## Verification
|
|
|
|
- [ ] Glossary is the final top-level menu item and has a dedicated sidebar.
|
|
- [ ] Every changed term has one canonical definition and stable link.
|
|
- [ ] Domain pages link rather than repeat glossary-style explanations.
|
|
- [ ] Scope, status, aliases, related terms, and authoritative links are present where applicable.
|
|
- [ ] Domain-owned evidence and decisions remain in their owning sections.
|
|
- [ ] Navigation, links, production build, deployed rendering, and immutable source readback pass.
|