# Word choice ## Cut the filler vocabulary Some words appear in drafts as decoration and carry no technical meaning. Delete the padding and keep the sentence: "it is important to note that" and "note that" add nothing. Prefer the short form: "to" instead of "in order to", "because" instead of "due to the fact that", and "can" instead of "has the ability to". Prefer the plain verb: "use" instead of "utilize" and "leverage", and "cover" instead of "delve into". Replace a vague quantity with the real one: name the range instead of "a wide range of", and count the options instead of "various". - Before: `In order to leverage the various caching options, note that the setup is straightforward.` - After: `To cache content, set the TTL and the cache key.` Keep a word from this family when it carries technical meaning. Cut it when it decorates. ## Avoid empty adjectives An empty adjective claims quality without describing behavior. Drop the adjective and state what the product does, what it withstands, or what it covers. [Documentation voice](/en/documentation/style-guide/writing/voice/) owns the register rule. This page covers the vocabulary. The test is whether the word claims *quality* or describes *behavior*. "Robust security" asks the reader to trust an adjective. "A robust retry with exponential backoff" names the mechanism, and the adjective now describes something testable. Keep a word that passes this test. Replace one that does not. The same failure hides in framing phrases. Write "Use for" instead of "Perfect for" or "Essential for", and "Use when" instead of "Best for". State the action directly instead of "empowers you to", and drop "modern", "seamless", and "cutting-edge" as modifiers. - Before: `Applications offers powerful, seamless caching, perfect for modern e-commerce.` - After: `Applications caches content on Azion's distributed infrastructure.` *Significance inflation* is the same failure aimed at a concept: a sentence about how important something is, in place of what it does. "Caching plays a crucial role in modern web performance" gives the reader nothing to act on. State what the thing does and what its limits are. ## Cut the padding patterns Five patterns add words without adding information. *Participle padding* is a trailing `-ing` clause: "…reducing latency and improving performance, ensuring a better experience." Cut the clause and keep the claim that is measurable. The sentence-level rule against trailing participles is in [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/). *Negative parallelism* is the shape "It's not just X, it's Y." Say Y. *False ranges* connect items that are not on a scale: "from configuration to deployment to monitoring". List the actual set instead. *Undefined "you can"* promises without content: "You can configure various options." Either name the options or link to the page that names them. *Generic conclusions* restate the page without adding anything. End on the last concrete fact, or on a link worth following. ## Vary the shape of consecutive sentences Two sentences in a row that open with the same words, or that share the same grammatical shape, read as a template even when every fact in them is right: - Before: `A data center that holds a valid copy answers from cache. A data center that holds no valid copy fetches the object from the origin.` - After: `When a data center holds a valid copy, it answers from cache. Otherwise the data center fetches the object from the origin.` Three techniques break the pattern: lead with the condition rather than the subject; contrast with a connective such as `Otherwise` instead of naming the subject twice; and let one sentence carry two clauses when they are one thought. A paragraph whose sentences all run the same mid-length reads the same way, so vary the length and prefer short. ## Name things in headings A heading names a thing or a task. A rhetorical question does neither. - Before: `What is caching?` - After: `Caching` - Before: `Why use Tiered Cache?` - After: `When to use Tiered Cache` ## Avoid these words on every page Do not call a task "simple", "easy", "straightforward", or "obvious", and do not soften a step with "just" or "simply". If the task were easy, the reader would not be here, and these words tell a stuck reader to feel embarrassed. Do not write "please". Documentation instructs. It does not ask. Do not anchor a page in time with "currently", "at the time of writing", "will soon", "now available", "recently", or "new" as a modifier. All of them age badly, and nobody returns to fix them. No month or year appears outside a changelog: say what is true and let the changelog carry the timeline. A date a build step generates, such as the last-updated column on a Guides and tutorials hub, is exempt, because nothing written by hand goes stale there. Write "for example" and "that is", never "e.g." and "i.e.". ## Use the interface verbs Each interface action takes one verb, the same verb on every page: | Use | Not | | ----------------- | ------------------------------------------ | | select | click, hit, tap | | go to | navigate to | | turn on, turn off | enable, disable (for switches and toggles) | | enter | type in, input | | refer to | see, check out | "Enable" and "disable" stay legitimate for describing state in prose: "When WAF is enabled on the firewall, requests pass through it." Do not use directional language. Name the element instead, per [Accessibility](/en/documentation/style-guide/writing/accessibility/). The step grammar that uses these verbs is in [Procedures](/en/documentation/style-guide/writing/procedures/). ## Use inclusive language The documentation addresses the reader as "you", so the generic reader never needs a gendered pronoun. A generic third party — an attacker, a developer — takes "they", never "he" or "she". Gendered and ableist idioms follow the same rule. Write `validate`, not `sanity check`. A role or a profession takes a neutral noun. Write `camera operator`, not `cameraman`. Replace a loaded technical term when the industry accepts an alternative: | Avoid | Use | | ------------ | --------------- | | whitelist | allowlist | | blacklist | blocklist | | master/slave | primary/replica | Do not use culture-specific references or idioms. They make sense in one locale, and they do not survive translation. Every page here ships in two languages, per [Bilingual pages](/en/documentation/style-guide/conventions/bilingual/). ## Drop the article before a product name A product name is a proper noun, so it takes no article. - Incorrect: `Access the Azion Console.` - Correct: `Access Azion Console.` The article returns when a common noun follows the name, because the article then belongs to that noun: `The Object Storage bucket holds the build output.` ## Use American English spelling Write `organize`, `behavior`, and `license`. British spellings drift into pages copied from vendor documentation, so check the ones that differ. ## Expand acronyms on first use The first use on every page spells out the term and puts the acronym in parentheses: `time to live (TTL)`. After that, the acronym stands alone. A reader lands on any page directly, from a search result, so a definition on another page does not exist for them. Product names are not acronyms. Write the name as the rules in [Documentation terminology](/en/documentation/style-guide/writing/terminology/) require, and do not expand it. ## Confirm every specific An invented specific is the worst failure in documentation. A wrong limit, default, field name, flag, or error string looks exactly like a correct one. The reader discovers the difference only when they try it and it fails. Every number, field name, and command comes from somewhere you can point to: the product itself, its API, or the team that owns it. When you cannot confirm a value, leave it out. A page that says less is recoverable. A page with a confident wrong value is not, because nobody knows to check it. Product names follow their own rules, in [Documentation terminology](/en/documentation/style-guide/writing/terminology/).