Terminology

We’re adopting high standards for terminology on docs.microsoft.com. Here’s a little background, what to do, and guidelines for all content contributors.

Background

  • What terminology is: Product names and key related technical terms. Ex. SQL Database and elastic pool

  • Why a priority: Documentation is key to adoption. Clear and consistent use of terms is the basis for a successful user experience with the docs

  • How users are derailed from learning our products if they can’t understand our terms:

    Quote from a user: The terminology in relationship to .net core is slippery at best and mind-numbing at worst. Is a platform a kind of abstract target… or always a tangible set of .net library files?... Can you all get into one room and decide what constitutes a platform, a package, a runtime, a framework, a library, a metapackage, and so on?

What to do

  • Create a list: Writing teams should create a short list of key names and terms. Make it part of your regular discussions with docs, engineering, marketing, and UX teams. If your team has a term lead they’ll create the list, if not you should. See the example list

  • Follow guidelines: Keep terms and definitions simple based on the guidelines in this article

  • Communicate: Make your list accessible to all contributors and refer to it routinely in meetings. It's the only way to consistency

  • Add to Acrolinx: Acrolinx is a QA tool that flags incorrect usage. Contact monicar to add terms that are prone to incorrect use. Ex. Use: Resource Manager/ Don’t use: ARM

  • Update: Review with all contributors and update periodically

Example list: SQL Database terminology

Note: Precede all service names with Azure at first mention, and then you can omit. Ex. Azure SQL Database, SQL Database

Term What it is, what it does Notes
database transaction unit (DTU) A unit of measure of the resources that are guaranteed to be available to a single SQL database at a specific performance level within a single database service tier Acronym is acceptable after first mention since this is not a branded service name
SQL Database A relational database-as-a-service in the cloud built on the Microsoft SQL Server engine Lowercase instance reference: SQL database
Etc.

Guidelines for product names

Note about the naming process: The Branding team creates high-level product and service names (ex. SQL Database, DocumentDB). Marketing and engineering traditionally create feature names and capabilities (elastic pool for SQL Database, scale sets for virtual machines). We are asking writers to work more closely with marketing and engineering to make use of writer expertise with these guidelines in mind:

  • Names. Not everything needs a name -- overnaming confuses users about our offerings. Names are for high-level products/services/features with a large marketing investment. Examples: SQL Server is a product name, DocumentDB is a service name, Resource Manager is a high-level feature. If you are creating a feature name follow MS conventions and be descriptive: Resource Manager vs. Lollipop

  • Capabilities: Lower-level features and capabilities do not require capitalized names. They are not key differentiators and are not backed by major marketing investment. Examples: storage tiering, network switch manager, core system server.

  • Acronyms: Avoid acronyms for product names. This is because they diminish the brand, discoverability, and user comprehension. Users buy names, not acronyms. An exception in technical documentation applies to references to commands that the user should run:

    Example: "You can create any number of Azure Container Service (ACS) instances in your subscription, up to the limit of your quota. To list all instances of ACS in your subscription run the command 'az acs list'."

Guidelines for terms

These examples will help you arrive at the shortest and clearest set of technical terms for your technology (with due respect to referenced teams):

  • Keep terms simple and don’t over-create: Don’t create terms that users will have to parse if an existing term is already adequate. Example: We don’t need a new term (standalone) to refer to a single database. Just use single database

  • Be consistent with the industry: Follow industry terms and existing Microsoft conventions wherever possible. A counterexample: We introduced the API Apps feature of App Service as a way to create microservices. But we initially avoided using the term microservice in favor of the general reference API app, which was extremely confusing internally and for users

  • Don’t ship the org chart: Example: R Server has an operationalization team and initially used operationalization as a term for the features that make R Server a server. The team then decided the term was complex and superfluous (other server products don’t use this term). Now the team refers directly to the features themselves (client/server functionality, roles, packaging, etc.) and they have eliminated operationalization as one of their terms

Additional resources