Verbs

Use verbs that are active, direct, and descriptive. Strong verb choices make documentation clearer, more concise, and more actionable for readers.

General Rules

Follow these rules to choose verbs that make your writing clear, direct, and easy for readers to act on.

• Use active verbs to describe actions clearly and efficiently. For example, “Create a Droplet” instead of “Droplets can be created.”

Use active voice by default. Passive voice is appropriate when it sounds more natural, avoids awkward phrasing, emphasizes the result, or when the actor is unknown, unimportant, or implied. For more details, see When Passive Voice Improves Clarity and Tone section.

• Use the present tense. Use the future tense only when the present would be unclear or inaccurate for future actions or outcomes. Be definitive about what happens when the user takes an action. For example, “Y happens,” not “Y will happen.”

• Use the imperative mood for procedural headings. Headings that introduce tasks or procedures should tell the reader what action to take. For example, “Create a Droplet,” “Configure Networking,” or “Delete an App”.

  Imperative headings are clearer and more direct, and improve consistency and scannability across docs.

• Prefer direct, concrete verbs that accurately describe what the user or system does. For examples, “Run the command,” “Restart the service,” “Update the file.”

• Avoid wordy constructions that weaken the sentence. Avoid “You will need to be able to run…”. Use the imperative (“Run…”).

• Avoid modal auxiliaries such as should, _could, may, and might, which can be confusing for non-native English speakers. Use direct, present-tense verbs instead.

When Passive Voice Improves Clarity and Tone

Passive voice is appropriate when it improves readability, avoids blaming or talking down to the user, or when the actor is implied, unknown, or unimportant.

The following example shows an intentional revision from active to passive voice to remove condescending language.