Devdictionary Best Practices: Building a Reliable Technical Resource

Open source projects live or die by how easily strangers can understand them. A contributor might arrive from a completely different tech stack, a different country, a different level of experience — and the first thing standing between them and a useful pull request is often not the code itself but the vocabulary wrapped around it. A well-built glossary is one of the highest-leverage documents an open source maintainer can write, because it pays off every single time someone new opens the repository.

Want expert help putting this into practice? Dev Dictionary can guide you through it.

Why open source projects need a glossary more than most

Inside a company, a new engineer usually gets a Slack channel, a mentor, and a few weeks of paid onboarding time to absorb the local jargon. Open source contributors get none of that by default. Someone fixing a typo today might submit a meaningful feature next month, and the gap between those two contributions is almost always vocabulary, not skill. A contributor who does not know what your project means by "worker," "adapter," "fixture," or "provider" will either guess wrong, ask in an issue and wait days for a reply, or quietly give up.

Because contributors come from such varied backgrounds — different languages, different frameworks, different professional contexts — a glossary does something a tutorial cannot: it lets people look up exactly the one term that is blocking them, without reading pages of unrelated setup instructions. This is especially true for terms that are common in one ecosystem but unfamiliar in another. A Python contributor coming to a Rust project needs "trait" explained; a frontend developer coming to a backend service needs "migration" explained. The glossary is the fastest path from confusion to a working mental model.

Keeping definitions accurate as the project evolves

Related: Devdictionary - Essential Steps to Mastering Technical Jargon.

The hardest part of maintaining a glossary is not writing it — it is keeping it true. Software projects change shape constantly: a module gets renamed, a pattern gets deprecated, a term that used to mean one thing gets repurposed to mean something narrower. A glossary that drifts out of sync with the actual codebase is worse than no glossary at all, because it actively misleads people who trust it.

A few practices keep drift under control:

• Treat the glossary file as part of the same pull request as any change that renames a concept, not as a follow-up task that gets forgotten.
• Add a lightweight review checklist item — "does this PR introduce or rename a public concept?" — to your contribution template, so renaming triggers a glossary reminder automatically.
• Periodically audit the glossary against the actual public API or CLI surface, deleting entries for anything that no longer exists rather than letting dead terms accumulate.
• Date-stamp or version-stamp entries for terms that have changed meaning across major releases, so someone reading old issues or old tutorials isn't misled by a term that used to mean something else.

Docs rot happens gradually, one skipped update at a time. The fix is not heroic effort but small, consistent friction built into the normal contribution workflow.

Crediting and reviewing community-contributed definitions

Glossaries improve fastest when contributors themselves can propose new entries or fix ones that misled them — after all, the person best positioned to notice a confusing definition is the person who was just confused by it. Treat glossary contributions like any other pull request: they should be reviewed, not simply merged, because an inaccurate or overly technical definition is a bug in the documentation even if it never breaks a build.

A good review standard for a submitted definition asks three things: is it accurate, is it understandable to someone who has never seen the codebase before, and does it avoid circular definitions that just point to other jargon? Crediting contributors — even with something as simple as a name in a changelog or a mention in release notes — signals that documentation work is valued as much as code, which in turn encourages more of it. Documentation contributions often draw more sustained community engagement than code contributions, precisely because the barrier to entry is lower.

Linking glossary terms from code, docstrings, and the README

See also: Devdictionary Best Practices: Building a Reliable and Useful Technical Glossary.

A glossary that lives in isolation, three clicks deep in a docs site, gets used far less than one that surfaces exactly where confusion happens. The most effective pattern is to link terminology at the point of first contact: a docstring that uses the word "handler" can link directly to the glossary entry for "handler," and a README that introduces "the reconciliation loop" can do the same. This turns the glossary from a reference document someone has to remember exists into a just-in-time explanation that appears exactly when it's needed.

This also has a secondary benefit for maintainers: if you find yourself wanting to link a term but there's no glossary entry for it, that's a strong signal the term needs one. Treating "does this need a glossary link?" as a habit while writing comments and docs naturally keeps the glossary comprehensive rather than an afterthought written once and abandoned.

Project-specific jargon versus borrowed ecosystem terms

Not every term in a codebase deserves the same treatment. It helps to separate two categories clearly. The first is project-specific jargon — words your project invented or repurposed, like an internal name for a plugin system or a nickname for a particular workflow. These terms exist nowhere else, so your glossary is the only place a newcomer can learn them, and the definition needs to be self-contained and precise.

The second category is terms borrowed from the wider ecosystem — things like "middleware," "idempotent," "race condition," or "dependency injection." These already have accepted meanings outside your project, so the entry doesn't need to reinvent the definition from scratch; it's more useful to give the standard definition briefly and explain how your project specifically implements the concept. Conflating the two is a common mistake: a long, generic explanation of "cache" when the reader actually needs to know how your project's cache invalidation works wastes their time, while a project-specific redefinition of a term that already has a widely understood meaning risks contradicting what the contributor already knows.

Making the glossary part of the contribution workflow

Ultimately, a glossary succeeds when it stops being a document and starts being a habit — something updated in the same breath as the code it describes, reviewed with the same rigor, and linked from the places people actually get stuck. Tools like Dev Dictionary exist for exactly this kind of terminology work, giving maintainers and contributors a shared, plain-English reference for the concepts that show up across projects, so the glossary isn't something built from zero every time. Pair that kind of external reference with your own project-specific entries, and new contributors get both halves of the picture: the general vocabulary of software development, and the specific vocabulary of your project.

The payoff compounds. Every clear definition you write once saves that same explanation from being typed out in an issue thread a dozen times over. For an open source project depending on volunteer time, that is one of the best returns on investment available.