mirror of https://github.com/istio/istio.io.git
6 lines
31 KiB
HTML
6 lines
31 KiB
HTML
<!DOCTYPE html><html lang="en" itemscope itemtype="https://schema.org/WebPage" style="overflow-y: scroll;"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="title" content="Style Guide"><meta name="og:title" content="Style Guide"><meta name="og:image" content="/v0.2/img/logo.png"/><meta name="description" content="Explains the dos and donts of writing Istio docs."><meta name="og:description" content="Explains the dos and donts of writing Istio docs."><title>Istioldie 0.2 / Style Guide</title><script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-98480406-2', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script><link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/v0.2/feed.xml"><link rel="apple-touch-icon" href="/v0.2/favicons/apple-touch-icon.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.2/favicons/android-chrome-96x96.png" sizes="96x96" ><link rel="icon" type="image/png" href="/v0.2/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.2/favicons/favicon-16x16.png" sizes="16x16"><link rel="manifest" href="/v0.2/favicons/manifest.json"><link rel="mask-icon" href="/v0.2/favicons/safari-pinned-tab.svg" color="#2DA6B0"><meta name="msapplication-TileColor" content="#ffffff"><meta name="msapplication-TileImage" content="/v0.2/favicons/mstile-150x150.png"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic"><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/v0.2/css/all.css"><link rel="stylesheet" href="/v0.2/css/prism.css"> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script></head><body class="language-unknown"><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation"><div class="container"><div class="row"><div class="col-md-11 nofloat center-block "><div class="navbar-header"> <button type="button" class="hamburger navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/v0.2/"><div> <img src="/v0.2/img/logo.png" alt="Istio" width="36px" height="54px"/> <span class="brand-name">Istioldie 0.2</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.2/about/" >About</a></li><li><a href="/v0.2/docs/" class='current'>Docs</a></li><li><a href="/v0.2/blog/" >Blog</a></li><li><a href="/v0.2/community/" >Community</a></li><li><a href="/v0.2/faq/" >FAQ</a></li><li class="dropdown"><li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href=""> <i class='fa fa-lg fa-cog'></i> <span class="caret"></span> </a><ul class="dropdown-menu"><h6 class="dropdown-header">Other versions of this site</h6><li> <a href="https://istio.io">Current Release</a></li><li> <a href="https://preliminary.istio.io">Next Release</a></li><li> <a href="https://archive.istio.io">Older Releases</a></li></ul></li><li><form name="cse" id="searchbox_demo" class="navbar-form navbar-right" role="search"> <input type="hidden" name="cx" value="013699703217164175118:iwwf17ikgf4" /> <input type="hidden" name="ie" value="utf-8" /> <input type="hidden" name="hl" value="en" /><div class="form-group"><div class="input-group"> <input name="q" class="form-control" type="text" size="30" /><div class="input-group-addon"> <span class="btn-search glyphicon glyphicon-search"></span></div></div></div></form> <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script></li></ul></div></div></div></div></nav></div><div class="container"><div class="row"><div class="col-md-11 nofloat center-block" style="margin-top: 3px;"><ul class="col-sm-10 nav nav-tabs"><li role="presentation" ><a href="/v0.2/docs/">Welcome</a></li><li role="presentation" ><a href="/v0.2/docs/concepts/">Concepts</a></li><li role="presentation" ><a href="/v0.2/docs/setup/">Setup</a></li><li role="presentation" ><a href="/v0.2/docs/tasks/">Tasks</a></li><li role="presentation" ><a href="/v0.2/docs/guides/">Guides</a></li><li role="presentation" class='active'><a href="/v0.2/docs/reference/">Reference</a></li></ul></div></div></div><script src="/v0.2/js/navtree.js"></script><div class="container docs"><div class="row"><div class="col-md-11 nofloat center-block"><div class="row"><div id="sidebar-container" class="col-sm-3"><ul class="doc-side-nav"><li><h5 class='doc-side-nav-title'>Reference</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "api", "index.md", ], url: "/docs/reference/api/", title: "API", order: 10, overview: "Detailed information on API parameters."}); docs.push({path: [ "api", "mixer", "index.md", ], url: "/docs/reference/api/mixer/", title: "Mixer", order: 10, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "api", "mixer", "mixer-service.md", ], url: "/docs/reference/api/mixer/mixer-service.html", title: "Mixer Service", order: 20, overview: "Generated documentation for Mixer's API Surface"}); docs.push({path: [ "api", "mixer", "status.md", ], url: "/docs/reference/api/mixer/status.html", title: "Status RPC", order: 40, overview: "Google's rpc.Status proto"}); docs.push({path: [ "commands", "index.md", ], url: "/docs/reference/commands/", title: "CLI", order: 30, overview: "Describes usage and options of the Istio CLI and other utilities."}); docs.push({path: [ "commands", "istio_ca.md", ], url: "/docs/reference/commands/istio_ca.html", title: "istio_ca", order: 301, overview: "Istio Certificate Authority (CA)"}); docs.push({path: [ "commands", "istioctl.md", ], url: "/docs/reference/commands/istioctl.html", title: "istioctl", order: 20, overview: "Istio control interface"}); docs.push({path: [ "commands", "mixc.md", ], url: "/docs/reference/commands/mixc.html", title: "mixc", order: 101, overview: "Utility to trigger direct calls to Mixer's API."}); docs.push({path: [ "commands", "mixs.md", ], url: "/docs/reference/commands/mixs.html", title: "mixs", order: 201, overview: "Mixer is Istio's abstraction on top of infrastructure backends."}); docs.push({path: [ "config", "index.md", ], url: "/docs/reference/config/", title: "Configuration", order: 20, overview: "Detailed information on configuration options."}); docs.push({path: [ "config", "mixer", "adapters", "denier.md", ], url: "/docs/reference/config/mixer/adapters/denier.html", title: "denier Config", order: 100, overview: "Generated documentation for Mixer's denier Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "index.md", ], url: "/docs/reference/config/mixer/adapters/", title: "Adapters", order: 40, overview: "Generated documentation for Mixer's adapters."}); docs.push({path: [ "config", "mixer", "adapters", "kubernetes.md", ], url: "/docs/reference/config/mixer/adapters/kubernetes.html", title: "kubernetes Config", order: 10, overview: "Generated documentation for Mixer's kubernetes Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "list.md", ], url: "/docs/reference/config/mixer/adapters/list.html", title: "list Config", order: 20, overview: "Generated documentation for Mixer's list Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "memquota.md", ], url: "/docs/reference/config/mixer/adapters/memquota.html", title: "memquota Config", order: 30, overview: "Generated documentation for Mixer's memquota Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "prometheus.md", ], url: "/docs/reference/config/mixer/adapters/prometheus.html", title: "prometheus Config", order: 40, overview: "Generated documentation for Mixer's prometheus Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "stackdriver.md", ], url: "/docs/reference/config/mixer/adapters/stackdriver.html", title: "stackdriver Config", order: 50, overview: "Generated documentation for Mixer's stackdriver Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "statsd.md", ], url: "/docs/reference/config/mixer/adapters/statsd.html", title: "statsd Config", order: 60, overview: "Generated documentation for Mixer's statsd Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "stdio.md", ], url: "/docs/reference/config/mixer/adapters/stdio.html", title: "stdio Config", order: 70, overview: "Generated documentation for Mixer's stdio Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "svcctrl.md", ], url: "/docs/reference/config/mixer/adapters/svcctrl.html", title: "svcctrl Config", order: 80, overview: "Generated documentation for Mixer's svcctrl Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "attribute-manifests.md", ], url: "/docs/reference/config/mixer/attribute-manifests.html", title: "Attribute Manifests", order: 15, overview: "Describes the resource containing the collection of attributes known to Mixer at runtime."}); docs.push({path: [ "config", "mixer", "attribute-vocabulary.md", ], url: "/docs/reference/config/mixer/attribute-vocabulary.html", title: "Attribute Vocabulary", order: 10, overview: "Describes the base attribute vocabulary used for policy and control."}); docs.push({path: [ "config", "mixer", "expression-language.md", ], url: "/docs/reference/config/mixer/expression-language.html", title: "Expression Language", order: 20, overview: "Mixer config expression language reference."}); docs.push({path: [ "config", "mixer", "index.md", ], url: "/docs/reference/config/mixer/", title: "Mixer", order: 30, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "config", "mixer", "policy-and-telemetry-rules.md", ], url: "/docs/reference/config/mixer/policy-and-telemetry-rules.html", title: "Policy and Telemetry Rules", order: 40, overview: "Describes the rules used to configure Mixer policy and telemetry."}); docs.push({path: [ "config", "mixer", "template", "checknothing.md", ], url: "/docs/reference/config/mixer/template/checknothing.html", title: "checknothing Config", order: 1150, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "index.md", ], url: "/docs/reference/config/mixer/template/", title: "Templates", order: 50, overview: "Generated documentation for Mixer's Templates."}); docs.push({path: [ "config", "mixer", "template", "listentry.md", ], url: "/docs/reference/config/mixer/template/listentry.html", title: "listentry Config", order: 1160, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "logentry.md", ], url: "/docs/reference/config/mixer/template/logentry.html", title: "logentry Config", order: 1170, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "metric.md", ], url: "/docs/reference/config/mixer/template/metric.html", title: "metric Config", order: 1180, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "quota.md", ], url: "/docs/reference/config/mixer/template/quota.html", title: "quota Config", order: 1190, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "reportnothing.md", ], url: "/docs/reference/config/mixer/template/reportnothing.html", title: "reportnothing Config", order: 1200, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "value-type.md", ], url: "/docs/reference/config/mixer/value-type.html", title: "Value Type", order: 50, overview: "Generated documentation for Mixer Config's Value Type"}); docs.push({path: [ "config", "service-mesh.md", ], url: "/docs/reference/config/service-mesh.html", title: "Service Mesh", order: 15, overview: "Global Configuration Schema"}); docs.push({path: [ "config", "traffic-rules", "destination-policies.md", ], url: "/docs/reference/config/traffic-rules/destination-policies.html", title: "Destination Policies", order: 30, overview: "Client-side traffic management policies configuration schema"}); docs.push({path: [ "config", "traffic-rules", "egress-rules.md", ], url: "/docs/reference/config/traffic-rules/egress-rules.html", title: "Egress Rules", order: 40, overview: "Routing configuration for traffic exiting the service mesh"}); docs.push({path: [ "config", "traffic-rules", "index.md", ], url: "/docs/reference/config/traffic-rules/", title: "Traffic Management Rules", order: 20, overview: "Detailed information on rules configuration and API exposed by Pilot for managing them."}); docs.push({path: [ "config", "traffic-rules", "routing-rules.md", ], url: "/docs/reference/config/traffic-rules/routing-rules.html", title: "Routing Rules", order: 20, overview: "Traffic routing rule configuration schema"}); docs.push({path: [ "contribute", "creating-a-pull-request.md", ], url: "/docs/reference/contribute/creating-a-pull-request.html", title: "Creating a Pull Request", order: 20, overview: "Shows you how to create a GitHub pull request in order to submit your docs for approval."}); docs.push({path: [ "contribute", "editing.md", ], url: "/docs/reference/contribute/editing.html", title: "Editing Docs", order: 10, overview: "Lets you start editing this site's documentation."}); docs.push({path: [ "contribute", "index.md", ], url: "/docs/reference/contribute/", title: "Contributing to the Docs", order: 100, overview: "Learn how to contribute to improve and expand the Istio documentation."}); docs.push({path: [ "contribute", "reviewing-doc-issues.md", ], url: "/docs/reference/contribute/reviewing-doc-issues.html", title: "Doc Issues", order: 60, overview: "Explains the process involved in accepting documentation updates."}); docs.push({path: [ "contribute", "staging-your-changes.md", ], url: "/docs/reference/contribute/staging-your-changes.html", title: "Staging Your Changes", order: 40, overview: "Explains how to test your changes locally before submitting them."}); docs.push({path: [ "contribute", "style-guide.md", ], url: "/docs/reference/contribute/style-guide.html", title: "Style Guide", order: 70, overview: "Explains the dos and donts of writing Istio docs."}); docs.push({path: [ "contribute", "writing-a-new-topic.md", ], url: "/docs/reference/contribute/writing-a-new-topic.html", title: "Writing a New Topic", order: 30, overview: "Explains the mechanics of creating new documentation pages."}); docs.push({path: [ "glossary.md", ], url: "/docs/reference/glossary.html", title: "Glossary", order: 40, overview: "A glossary of common Istio terms."}); docs.push({path: [ "index.md", ], url: "/docs/reference/", title: "Reference", order: 60, overview: "The Reference section contains detailed authoritative reference material such as command-line options, configuration options, and API calling parameters."}); docs.push({path: [ "notes", "0.1.md", ], url: "/docs/reference/notes/0.1.html", title: "Istio 0.1", order: 50, overview: ""}); docs.push({path: [ "notes", "index.md", ], url: "/docs/reference/notes/", title: "Prior Release Notes", order: 600, overview: "Release notes for prior versions of Istio."}); docs.push({path: [ "release-notes.md", ], url: "/docs/reference/release-notes.html", title: "Release Notes", order: 50, overview: "What's been happening with Istio"}); docs.push({path: [ "release-roadmap.md", ], url: "/docs/reference/release-roadmap.html", title: "Roadmap", order: 60, overview: "What Istio will become in the coming months."}); docs.push({path: [ "writing-config.md", ], url: "/docs/reference/writing-config.html", title: "Writing Configuration", order: 70, overview: "How to write Istio config YAML content."}); genNavBarTree(docs) </script></ul></div><div id="tab-container" class="col-xs-1 tab-neg-margin pull-left"> <a id="sidebar-tab" class="glyphicon glyphicon-chevron-left" href="javascript:void 0;"></a></div><div id="content-container" class="thin-left-border col-sm-9 markdown"><div id="toc" class="toc"></div><div id="doc-content"><h1>Style Guide</h1><p>TBD: This needs to be updated with Istio examples instead of Kubernetes examples.</p><p>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.</p><p>For additional information on creating new content for the Istio docs, follow the instructions on <a href="./creating-a-pull-request.html">Creating a Doc Pull Request</a>.</p><h2 id="formatting-standards">Formatting standards</h2><h3 id="use-camelcase-for-api-objects">Use camelCase for API objects</h3><p>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 <a href="https://en.wikipedia.org/wiki/Camel_case">camelCase</a>.</p><p>Don’t split the API object name into separate words. For example, use PodTemplateList, not Pod Template List.</p><p>Refer to API objects without saying “object,” unless omitting “object” leads to an awkward construction.</p><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>The Pod has two Containers.</td><td>The pod has two containers.</td></tr><tr><td>The Deployment is responsible for …</td><td>The Deployment object is responsible for …</td></tr><tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr><tr><td>The two ContainerPorts …</td><td>The two ContainerPort objects …</td></tr><tr><td>The two ContainerStateTerminated objects …</td><td>The two ContainerStateTerminateds …</td></tr></tbody></table><h3 id="use-angle-brackets-for-placeholders">Use angle brackets for placeholders</h3><p>Use angle brackets for placeholders. Tell the reader what a placeholder represents.</p><ol><li><p>Display information about a pod:</p><pre><code> kubectl describe pod <pod-name>
|
||
</code></pre><p>where <code><pod-name></code> is the name of one of your pods.</p></li></ol><h3 id="use-bold-for-user-interface-elements">Use <strong>bold</strong> for user interface elements</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>Click <strong>Fork</strong>.</td><td>Click “Fork”.</td></tr><tr><td>Select <strong>Other</strong>.</td><td>Select ‘Other’.</td></tr></tbody></table><h3 id="use-italics-to-define-or-introduce-new-terms">Use <em>italics</em> to define or introduce new terms</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>A <em>cluster</em> is a set of nodes …</td><td>A “cluster” is a set of nodes …</td></tr><tr><td>These components form the <em>control plane</em>.</td><td>These components form the <strong>control plane</strong>.</td></tr></tbody></table><h3 id="use-code-style-for-filenames-directories-and-paths">Use <code>code</code> style for filenames, directories, and paths</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr><tr><td>Go to the <code>/_docs/tasks</code> directory.</td><td>Go to the /docs/tasks directory.</td></tr><tr><td>Open the <code>_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr></tbody></table><h3 id="use-code-style-for-inline-code-and-commands">Use <code>code</code> style for inline code and commands</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The “kubectl run” command creates a Deployment.</td></tr><tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use “kubectl apply”.</td></tr></tbody></table><h3 id="use-code-style-for-object-field-names">Use <code>code</code> style for object field names</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the “replicas” field in the configuration file.</td></tr><tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the “exec” field is an ExecAction object.</td></tr></tbody></table><h3 id="use-normal-style-for-string-and-integer-field-values">Use normal style for string and integer field values</h3><p>For field values of type string or integer, use normal style without quotation marks.</p><table><thead><tr><th>Do</th><th>Don’t</th><th> </th><th> </th></tr></thead><tbody><tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to “Always”.</td><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr><tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td><td> </td><td> </td></tr></tbody></table><h3 id="only-capitalize-the-first-letter-of-headings">Only capitalize the first letter of headings</h3><p>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.</p><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>Configuring rate limits</td><td>Configuring Rate Limits</td></tr><tr><td>Using Envoy for ingress</td><td>Using envoy for ingress</td></tr><tr><td>Using HTTPS</td><td>Using https</td></tr></tbody></table><h2 id="code-snippet-formatting">Code snippet formatting</h2><h3 id="dont-include-the-command-prompt">Don’t include the command prompt</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr></tbody></table><h3 id="separate-commands-from-output">Separate commands from output</h3><p>Verify that the pod is running on your chosen node:</p><pre><code class="language-bash">kubectl get pods --output=wide
|
||
</code></pre><p>The output is similar to this:</p><pre><code class="language-bash">NAME READY STATUS RESTARTS AGE IP NODE
|
||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||
</code></pre><h2 id="terminology-standards">Terminology standards</h2><p>Some standard terms we want to use consistently within the documentation for clarity.</p><h3 id="envoy">Envoy</h3><p>We prefer to use “Envoy” as it’s a more concrete term than “proxy” and will resonate if used consistently throughout the docs.</p><p>Synonyms:</p><ul><li>“Envoy sidecar” - ok</li><li>“Envoy proxy” - ok</li><li>“The Istio proxy” – best to avoid unless you’re talking about advanced scenarios where another proxy might be used.</li><li>“Sidecar” – mostly restricted to conceptual docs</li><li>“Proxy – only if context is obvious</li></ul><p>Related Terms</p><ul><li>Proxy agent - This is a minor infrastructural component and should only show up in low-level detail documentation. It is not a proper noun.</li></ul><h3 id="mixer">Mixer</h3><p>Mixer is a proper noun and should be used as such:</p><ul><li>“You configure Mixer by ….”</li><li>“Mixer provides a standard vehicle for implementing organizational wide policy”</li></ul><h3 id="attributes">Attributes</h3><p>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.</p><h3 id="load-balancing">Load balancing</h3><p>No dash, it’s <em>load balancing</em> not <em>load-balancing</em>.</p><h3 id="service-mesh">Service mesh</h3><p>Not a proper noun. Use in place of service fabric.</p><h3 id="service-version">Service version</h3><p>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.</p><h2 id="content-best-practices">Content best practices</h2><p>This section contains suggested best practices for clear, concise, and consistent content.</p><h3 id="use-present-tense">Use present tense</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr></tbody></table><p>Exception: Use future or past tense if it is required to convey the correct meaning.</p><h3 id="use-active-voice">Use active voice</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr><tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr></tbody></table><p>Exception: Use passive voice if active voice leads to an awkward construction.</p><h3 id="use-simple-and-direct-language">Use simple and direct language</h3><p>Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”</p><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>To create a ReplicaSet, …</td><td>In order to create a ReplicaSet, …</td></tr><tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr><tr><td>View the Pods.</td><td>With this next command, we’ll view the Pods.</td></tr></tbody></table><h3 id="address-the-reader-as-you">Address the reader as “you”</h3><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>You can create a Deployment by …</td><td>We’ll create a Deployment by …</td></tr><tr><td>In the preceding output, you can see…</td><td>In the preceding output, we can see …</td></tr></tbody></table><h2 id="patterns-to-avoid">Patterns to avoid</h2><h3 id="avoid-using-we">Avoid using “we”</h3><p>Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.</p><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>Version 1.4 includes …</td><td>In version 1.4, we have added …</td></tr><tr><td>Kubernetes provides a new feature for …</td><td>We provide a new feature …</td></tr><tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr></tbody></table><h3 id="avoid-jargon-and-idioms">Avoid jargon and idioms</h3><p>Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.</p><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>Internally, …</td><td>Under the hood, …</td></tr><tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr></tbody></table><h3 id="avoid-statements-about-the-future">Avoid statements about the future</h3><p>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.</p><h3 id="avoid-statements-that-will-soon-be-out-of-date">Avoid statements that will soon be out of date</h3><p>Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.</p><table><thead><tr><th>Do</th><th>Don’t</th></tr></thead><tbody><tr><td>In version 1.4, …</td><td>In the current version, …</td></tr><tr><td>The Federation feature provides …</td><td>The new Federation feature provides …</td></tr></tbody></table></div></div></div></div></div></div><script src="/v0.2/js/sidemenu.js"></script><footer><div class="container"><div class="row"><div class="col-md-2"></div><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Docs</p><li><a href="/v0.2/docs/">Welcome</a></li><li><a href="/v0.2/docs/concepts">Concepts</a></li><li><a href="/v0.2/docs/setup">Setup</a></li><li><a href="/v0.2/docs/tasks">Tasks</a></li><li><a href="/v0.2/docs/guides">Guides</a></li><li><a href="/v0.2/docs/reference">Reference</a></li></ul></div><hr class="footer-sections" /><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Resources</p><li><a href="/v0.2/faq">Frequently Asked Questions</a></li><li><a href="/v0.2/troubleshooting">Troubleshooting Guide</a></li><li><a href="/v0.2/bugs">Report a Bug</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/reference/contribute/style-guide.md">Report a Doc Issue</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/reference/contribute/style-guide.md">Edit This Page on GitHub</a></li></ul></div><hr class="footer-sections" /><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Community</p><li><a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank"><span class="group">User</span></a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank">Dev</a> | <a href="https://github.com/istio/istio/blob/master/GROUPS.md#working-groups" target="_blank">Working Group Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank"><span class="twitter">Twitter</span></a></li><li><a href="https://github.com/istio/istio" target="_blank"><span class="github">GitHub</span></a></li></ul></div><div class="col-md-1"></div></div><div class="row"><p class="description small text-center"> Istio 0.2, Copyright © 2017 Istio Authors<br> Archived on 12-Nov-2017</p></div></div></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.2.1/jquery.form.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-visible/1.2.0/jquery.visible.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/slick-carousel/1.6.0/slick.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script> <script src="/v0.2/js/common.js"></script> <script src="/v0.2/js/buttons.js"></script> <script src="/v0.2/js/search.js"></script> <script src="/v0.2/js/prism.js"></script></body></html>
|