Language and Grammar

Within this section on language and grammar, you'll discover the primary information and guidelines to navigate the complexities of grammar. From abbreviations and active voice to sentence structure and contractions, we've compiled a set of standards to make your writing clear, concise, and easily understandable.

Guidelines

Abbreviations and acronyms

It's important to explain unfamiliar abbreviations or acronyms when first introducing them to readers. After the initial mention, you can use the abbreviated form for subsequent references. If the abbreviation doesn't clearly indicate its corresponding full version, clarify it in parentheses.

1️⃣ First use	2️⃣ Second use
Content Management System (CMS)	CMS
Product Backlog Item (PBI)	PBI

If the abbreviation or acronym is well known, like UX or HTML, use it instead (and don’t worry about spelling it out).

Active voice

Use active voice. Avoid passive voice.

In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.

❌   Not recommended	👍   Recommended
The software update is deployed to the server by the team.	The team deploys the software update to the server.
The user input is processed by the API, and the result is returned.	The API processes the user input and returns the result.

Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.

Capitalization

There are a few different forms of capitalization. Title case capitalizes the first letter of every word except articles, prepositions, and conjunctions. Sentence case capitalizes the first letter of the first word. Furthermore, don't capitalize random words in the middle of sentences.

When writing out an email address or website URL, use all lowercase.

👍
info@example.com
example.com

Contractions

Typically, we use an informal tone when writing our documentation and therefore suggest using contractions in most instances.

Pronouns

When the gender of the subject is not known or not important, it is appropriate to use singular pronouns such as "they," "them," and "their." However, when the gender is known, it is appropriate to use "he/him/his" or "she/her/her" pronouns accordingly. Avoid using "one" as a pronoun.

Sentence structure

When providing instructions, mentioning the circumstance, conditions, or goal beforehand is helpful. This approach allows the reader to skip the instruction if it is not applicable.

❌   Not recommended	👍   Recommended
Click Next if you want to install the plugin.	To install the plugin, click Next.
Read this text below if you want to understand all aspects.	To understand all aspects, read this text below.