Skip to content

Add plain-language glossary to lower the language barrier for new contributors#4

Draft
Copilot wants to merge 2 commits into
mainfrom
copilot/improve-language-barrier
Draft

Add plain-language glossary to lower the language barrier for new contributors#4
Copilot wants to merge 2 commits into
mainfrom
copilot/improve-language-barrier

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 6, 2026

The repository's documentation uses heavy domain-specific jargon (fractal, substrate-agnostic, entropy, cadence, invariant, IVERO, graceful degradation, etc.) with no centralized reference, creating a steep language barrier for newcomers and non-native English speakers.

Changes

New: docs/onboarding/GLOSSARY.md

  • Alphabetical glossary of 27 terms used across the system
  • Each entry includes a plain-English definition, an everyday analogy callout, and relevant file/action references
  • Quick Reference table at the end for fast lookups

Updated onboarding entry points

  • README.md — Glossary added as step 1 in For New Contributors; added to Documentation → For Learning
  • docs/onboarding/CONTRIBUTING.md — Glossary added as step 1 in Before You Contribute and in Further Reading
  • docs/onboarding/MENTAL_MODEL.md — Added to Further Reading
  • docs/ARCHITECTURE_OVERVIEW.md — Added to Further Reading

Example glossary entry:

### Substrate
The execution environment a workflow runs in: GitHub Actions runner, Docker
container, or local machine. Core behavior is "substrate-agnostic" — it works
the same regardless of which substrate it runs on.

**Plain English:** The platform or environment where a workflow actually runs.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: QueenFi703 <174653334+QueenFi703@users.noreply.github.com>
Copilot AI changed the title [WIP] Improve strategies to address language barriers Add plain-language glossary to lower the language barrier for new contributors Mar 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants