Documentation voice

Address the reader as “you”

Documentation speaks to the person who does the work. Second person keeps the reader inside the sentence, as the subject of the verb. “The user” turns the reader into a third party and pushes the verb toward the future.

Before: The user will create a bucket.
After: You create a bucket.

Use the simple present tense

Describe product behavior in the simple present. The present states what the platform does every time, and that is the claim a reader acts on.

Before: Applications will cache content on Azion's distributed infrastructure.
After: Applications caches content on Azion's distributed infrastructure.

Sentence structure owns the full tense rules, including the ban on tenses built with auxiliary verbs.

Use the active voice

The active voice names the actor. The passive hides the actor, and the actor is often the answer the reader came for.

Before: A cache policy is applied to the request.
After: Rules Engine applies a cache policy to the request.

The passive version leaves open who applies the policy: the platform, the browser, or the reader. In descriptive text, the passive is acceptable only when the actor is genuinely unknown or is the platform itself. Never use the passive in a step.

Write steps in the imperative

A step is an instruction, so it starts with the verb: Select **Save**., never “You should select” or “The button should be selected”. Procedures owns the step grammar.

Describe behavior, not quality

Documentation describes behavior and limits. It does not sell, because the reader already chose the product. An adjective that claims quality gives the reader nothing to act on; a behavior and a limit do.

Before: Applications offers powerful, flexible caching capabilities.
After: Applications caches content on Azion's distributed infrastructure. The default TTL is 60 seconds.

The rewrite replaces two adjectives with facts the reader can test. The vocabulary rules are in Word choice.

Split long sentences, do not clip them

Short sentences carry technical content better than long ones. Short is not the same as clipped: never drop a subject, a verb, or an article to shorten a sentence. When a sentence runs long, split it in two instead. Sentence structure owns this rule and the length caps.

Do not use contractions

Write “do not”, “cannot”, and “it is”. Contractions read casually and translate unevenly.

Before: You don't need to configure the origin again.
After: You do not need to configure the origin again.

Do not write “we”

Never write “we”. The actor is “Azion” or “you”. “We” names neither the platform nor the reader, so the reader cannot tell who acts.

Before: We recommend a TTL of 60 seconds.
After: Azion recommends a TTL of 60 seconds.