This page provides content guidelines for the Istio documentation. These are guidelines, not rules, so use your best judgment, and feel free to propose changes to this document in a pull request.
Use consistent capitalization
Don't split configuration type names into separate words and follow the original capitalization. For
Istio Role Binding or
istio role binding.
Use angle brackets for placeholders
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
Display information about a pod:
$ kubectl describe pod <pod-name>
<pod-name>is the name of one of your pods.
Use bold for user interface elements
|Click Fork.||Click “Fork”.|
|Select Other.||Select ‘Other’.|
Use italics to define or introduce new terms
|A cluster is a set of nodes …||A “cluster” is a set of nodes …|
|These components form the control plane.||These components form the control plane.|
code style for filenames, directories, and paths
|Open the ||Open the foo.yaml file.|
|Go to the ||Go to the /content/docs/tasks directory.|
|Open the ||Open the /data/args.yaml file.|
code style for inline code and commands
|The ||The “foo run” command creates a |
|For declarative management, use ||For declarative management, use “foo apply”.|
code style for object field names
|Set the value of the ||Set the value of the “ports” field in the configuration file.|
|The value of the ||The value of the “rule” field is a |
Use title capitalization for
The text for the
title: front-matter should use full title capitalization
(first letter of every word). This is unlike headings within the document,
as described below.
Only capitalize the first letter of headings
For any headings, only apply an uppercase letter to the first word of the heading,
except if a word is a proper noun or an acronym. Note that the
in markdown uses full capitalization.
|Configuring rate limits||Configuring Rate Limits|
|Using Envoy for ingress||Using envoy for ingress|
|Using HTTPS||Using https|
Some standard terms we want to use consistently within the documentation for clarity.
We prefer to use “Envoy” as it’s a more concrete term than “proxy” and will resonate if used consistently throughout the docs.
- “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
- Proxy agent - This is a minor infrastructural component and should only show up in low-level detail documentation. It is not a proper noun.
Use present tense
|This command starts a proxy.||This command will start a proxy.|
Exception: Use future or past tense if it is required to convey the correct meaning.
Use active voice
|You can explore the API using a browser.||The API can be explored using a browser.|
|The YAML file specifies the replica count.||The replica count is specified in the YAML file.|
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.”
|To create a ||In order to create a |
|See the configuration file.||Please see the configuration file.|
|View the Pods.||With this next command, we'll view the Pods.|
Address the reader as “you”
|You can create a ||We'll create a |
|In the preceding output, you can see…||In the preceding output, we can see …|
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.
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.
|Version 1.4 includes …||In version 1.4, we have added …|
|Istio provides a new feature for …||We provide a new feature …|
|This page teaches you how to use pods.||In this page, we are going to learn about pods.|
Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.
|Internally, …||Under the hood, …|
|Create a new cluster.||Turn up a new cluster.|
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.
|In version 1.4, …||In the current version, …|
|The Federation feature provides …||The new Federation feature provides …|
Shows you how to use GitHub to work on Istio documentation.
Explains the mechanics of creating new documentation pages.