Education style guide

This document provides writing style guidance for authors who create and maintain product documentation, tutorials, WAF articles, and certifications content.

Purpose

Writing in a consistent style and voice makes the HashiCorp brand strong and vibrant. Our style guide reflects these goals:

Optimize for non-native speakers: HashiCorp has users all over the world, many of whom do not speak English as a first, second, or third language. Translation tools are not very smart, and even literal translations do not mean the same thing in different languages.
Optimize for tired operators: Many HashiCorp tools are in the path of downtime. While we strive to make the best tools in the world, sometimes they fail. Flowery sentences are not helpful when trying to get a system back online.
Optimize for content authors: When we write in the same style, we can spend more time focusing on the content and body of a pull request or documentation change, instead of pointing out small style inconsistencies.
Optimize for multiple products: A user who is familiar with the Consul documentation that chooses to adopt Vault should not feel as though they need to learn an entire new language just to read the docs. Consistency helps our overall adoption strategy.

Guiding principles

Never use a metaphor, simile, or other figure of speech even if you are used to seeing it in print.
Never use a long word where a short one will do.
If it is possible to cut a word out, always cut it out.
Never use the passive voice where you can use the active voice.
Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
If adhering to any of the guidelines does more harm than good, break the rule.

Content scope

Before conforming to a guideline, check the content sets list to verify that it applies to your content. The list contains one or more of the following content types:

docs
tutorials
WAF
certs

Deviations

If you feel that you need to break any of these guidelines, you might be right. Work with your technical writer when you think the context requires deviating from the standard guidance.

Fallbacks

This style guide is intended to be a complete resource, but you can take the following steps if you are unable to find appropriate guidance.

Ask your technical writer.
Consult a dictionary, such as Merriam-Webster, when missing guidance is related to spelling, capitalization, or grammar.
Consult the corporate style guide.
Consult the Google style guide.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!