Creating a Technical Concepts Glossary

Software has an ever changing vocabulary of patterns, techniques, concepts and terms. A lot of this can come off like jargon. When people get together and discuss ideas in a professional context, they often rely on a shared context. This is fine as long as all participants are familiar with the specific jargon being used but can become intimidating to people who aren’t. Hopefully there’s enough psychological safety that someone can ask, “I’m not familiar with x, can you explain it?” but that may not always be the case.

I try to be aware whenever I’m using jargon and create space for people to ask questions. I’ve definitely been in the position of having to ask someone to describe an idea or term.

To this end, I’ve decided to start writing it down whenever I get a clarifying question or ask one myself about a common bit of jargon. I started with a collection of notes in a Dropbox folder as a way of seeding future blog post content. I’ve since decided that a Github repo is a good place for a repository of documents like this, so I created one. As of this writing, it’s pretty basic – but I plan to add content there as I have time. Maybe it’ll be helpful to some people; maybe it won’t!

Obviously the content I create will be related to the kind of work I do, so expect things related to reliability, backend or platform engineering, scaling, architecture, etc. There are worlds of jargon that I have no idea about.

If you’d like to help out in any way, please do contribute! I’d love for people to file issues describing terms they’ve seen cause confusion, or submit Pull Requests with content. If there’s a term or idea that you’re confused about and don’t feel comfortable publicly saying so, you can also fill out this anonymous Google Form and I’ll do my best to get it added.

As we say at my work, everything is an experiment!