Writing style

Generally, HashiCorp follows the 2020 AP Stylebook rules and guidelines, unless HashiCorp specific style is indicated.

Capitalization

Headings and labels

Use sentence case for titles, headings, labels, links, and buttons. Use title case for proper nouns and when referring to products (e.g., Nomad).

Feature names

Avoid capitalizing feature names or internal constructs as proper nouns.

Capitalization for direction

When referring to specific UI elements or sections within the application, use the same capitalization of the element itself.

Exceptions for feature names

The following terms should always use title case:

• Terraform Registry
• Terraform Stacks
• Raft Algorithm
• Vault Agent
• Vault Proxy
• Boundary Client Agent / Client Agent (when referring to the Boundary Client Agent)
• Terraform Plugin Framework
• Nomad Autoscaler
• The Infrastructure Cloud
• Infrastructure Lifecycle Management
• Security Lifecycle Management

Grammar

Use “you” for the user

Directly addressing the user as "you" conveys the content in a more personal and informal way.

Use “we” for HashiCorp

Use “we” to describe recommendations by HashiCorp. Our language should never try to hedge or evade responsibility for the guidance we’re providing.

Active voice

Use active voice whenever possible. An active voice is when we communicate a subject performs an action on an object, instead of the subject being acted upon:

Use simple present tense

Don't avoid the imperative if you're telling someone to do something.

Uncommon acronyms

The first time an acronym or abbreviation is used, include the abbreviated word in parentheses. Subsequent mentions can use the acronym by itself. This does not apply to common acronyms like ID, IP, or API.

Consistent terminology

Use a verb followed by a noun when labeling actions.

Common actions

When possible, add an icon to action labels. Typically, the icon should represent the action (verb), but sometimes, it can represent the object (noun).

Create and Delete

Use when a new entity is produced or destroyed in the system, e.g., "Create a project" or "Delete a project", where the project didn't exist before or will no longer exist.

Add and Remove

Use when a new relationship or dependency between existing objects is produced or destroyed, e.g., "Add a user" (to a project), "Remove a user" (from a project), where both the user and the project already existed and will continue to exist, but the relationship itself is established or dissolved.

Edit and View

Use when editing or viewing an entity, e.g. "Edit project" or "View project," where the project will be modified for accuracy or previewed for quality assurance.

When editing an object, use "Save" for the action label. When applying another action, use an imperative, present-tense verb.

Punctuation

Serial/Oxford comma

Use the serial (“Oxford”) comma in lists.

Exclamation points

Avoid using exclamation points. Only use it if you’re connecting with understood, strong reader emotion.

Percentages

Use the % symbol instead of writing “percent,” e.g., “50%.”

Dashes

Use an en dash (–) to indicate a range or span of numbers.

Spelling

Use American English to help promote consistency across our products.