Style Guide

Here you can find all the scenarios where the Istio project has decided to follow a different practice and basic style guidance with Istio-specific examples.

Use sentence case for the headings in your document. Only capitalize the first word of the heading, except for proper nouns or acronyms.

Use title case for the value of the title: field of the front-matter

Use present tense

Exception: Use future or past tense if it is required to convey the correct meaning. This exception is extremely rare and should be avoided.

Use simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”

Address the reader as “you”

Avoid using “we”

Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.

Avoid using wording that becomes outdated quickly like “currently” and “new”. A feature that is new today is not new for long.