Style Guide

TBD: This needs to be updated with Istio examples instead of Kubernetes examples.

This page gives writing style guidelines for the Istio documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

For additional information on creating new content for the Istio docs, follow the instructions on Creating a Doc Pull Request.

Formatting standards

Use camelCase for API objects

When you refer to an API object, use the same uppercase and lowercase letters that are used in the actual object name. Typically, the names of API objects use camelCase.

Don’t split the API object name into separate words. For example, use PodTemplateList, not Pod Template List.

Refer to API objects without saying “object,” unless omitting “object” leads to an awkward construction.

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents.

1. Display information about a pod:

   kubectl describe pod <pod-name>
   

where <pod-name> is the name of one of your pods.

Use bold for user interface elements

Use italics to define or introduce new terms

Use code style for filenames, directories, and paths

Use code style for inline code and commands

Use code style for object field names

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

Only capitalize the first letter of headings

For any headings, only apply an uppercase letter to the first word of the heading, except is a word is a proper noun or an acronym.

Code snippet formatting

Don’t include the command prompt

Separate commands from output

Verify that the pod is running on your chosen node:

kubectl get pods --output=wide

The output is similar to this:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Terminology standards

Some standard terms we want to use consistently within the documentation for clarity.

Envoy

We prefer to use “Envoy” as it’s a more concrete term than “proxy” and will resonate if used consistently throughout the docs.

Synonyms:

• “Envoy sidecar” - ok
• “Envoy proxy” - ok
• “The Istio proxy” – best to avoid unless you’re talking about advanced scenarios where another proxy might be used.
• “Sidecar” – mostly restricted to conceptual docs
• “Proxy – only if context is obvious

Related Terms

• Proxy agent - This is a minor infrastructural component and should only show up in low-level detail documentation. It is not a proper noun.

Mixer

Mixer is a proper noun and should be used as such:

• “You configure Mixer by ….”
• “Mixer provides a standard vehicle for implementing organizational wide policy”

Attributes

Not a proper noun but we should attempt to consistently use the term to describe inputs to Mixer and NOT use the term when talking about other forms of configuration.

Load balancing

No dash, it’s load balancing not load-balancing.

Service mesh

Not a proper noun. Use in place of service fabric.

Service version

Use in the context of routing and multiple finer-grained versions of a service. Avoid using “service tags” or “service labels” which are the mechanism to identify the service versions, not the thing itself.

Content best practices

This section contains suggested best practices for clear, concise, and consistent content.

Use present tense

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

Exception: Use passive voice if active voice leads to an awkward construction.

Use simple and direct language

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

Address the reader as “you”

Create useful links

There are good hyperlinks, and bad hyperlinks. The common practice of calling links here or click here are examples of bad hyperlinks. Check out this excellent article explaining what makes a good hyperlink and try to keep these guidelines in mind when creating or reviewing site content.

Why “click here” is a terrible link, and what to write instead.

Patterns to avoid

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 statements about the future

Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.

Avoid statements that will soon be out of date

Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.