Normalize terminology in our community-facing docs and communication

During some usability testing, a new community member had difficulty finding the page about different instance sizes, possibly because the site navigation doesn't call them instances at all. The page is called "VM Sizes and Configurations", and they didn't recognize this term. The same community member also asked what a "flavor" is, I explained it's the same thing as an instance size.

It appears that our current use of terms is all over the place. This makes our documentation and overall service less legible, especially to new community members. So, this is an opportunity to improve UX and reduce the difficulty of user onboarding.

Term Number of uses in docs site Markdown1
instance 429
VM 149
virtual machine 52
server 101
flavor 60
size 86

For background, see also Nomenclature Reference in the Exosphere documentation, where we cataloged ~18 cloud-related concepts that often go by different names. A few years ago, we made the "Jetstream term" column of that table in consultation with @jlf599, but it may be out of date now.

We should consider:

  • Revisit and confirm our preferred terms for cloud-related concepts.
    • (Perhaps starting with the 18 defined in Exosphere's nomenclature doc.)
  • Provide a glossary of preferred terms, and all their common synonyms, on the docs site.
    • (There is already a brief Cacao-related glossary in there, but not a site-wide glossary.)
    • This can serve as a style guide for ourselves, and for community members contributing tutorials and the like.
    • We can also link to it from the docs site contributing.md.
  • Normalize the documentation site to use preferred terms.
  • Default to using preferred terms when we answer support tickets and write other community-facing text (like status page messages, newsletters, etc.) as well.

This is probably one for @lemaiw's team to lead (maybe @zacharygraber since he has been docs-focused lately?), but I'm happy to help.

  1. output of, e.g., grep -ir --include "*.md" instance . | wc -l across the docs repo. ↩