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.”

  Active voice should be your default choice, but passive voice is appropriate when it sounds more natural, avoids awkward phrasing, or keeps the focus on the result rather than the actor. Use passive voice when the doer of the action is unknown, unimportant, or implied. For example, “The file is created automatically” and “The request was denied due to invalid credentials.”

• Use verbs in the present tense, not the future tense. Be definitive about what happens when the user takes an action. For example, “Y happens,” not “Y will happen.”

• 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 unnecessary auxiliary verbs or wordy constructions that weaken the sentence. Avoid: “You will need to be able to run…” instead use: “Run…”

• Rewrite vague or abstract phrasing with more specific verbs when possible.