mirror of https://github.com/istio/istio.io.git
6 lines
23 KiB
HTML
6 lines
23 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.3/img/logo.png"/><meta name="theme-color" content="#466BB0"/><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.3 / 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.3/feed.xml"><link rel="shortcut icon" href="/v0.3/favicons/favicon.ico" ><link rel="apple-touch-icon" href="/v0.3/favicons/apple-touch-icon-180x180.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.3/favicons/favicon-16x16.png" sizes="16x16"><link rel="icon" type="image/png" href="/v0.3/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.3/favicons/android-36x36.png" sizes="36x36"><link rel="icon" type="image/png" href="/v0.3/favicons/android-48x48.png" sizes="48x48"><link rel="icon" type="image/png" href="/v0.3/favicons/android-72x72.png" sizes="72x72"><link rel="icon" type="image/png" href="/v0.3/favicons/android-96x196.png" sizes="96x196"><link rel="icon" type="image/png" href="/v0.3/favicons/android-144x144.png" sizes="144x144"><link rel="icon" type="image/png" href="/v0.3/favicons/android-192x192.png" sizes="192x192"><link rel="manifest" href="/v0.3/manifest.json"><meta name="apple-mobile-web-app-title" content="Istio"><meta name="application-name" content="Istio"><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.3/css/all.css"><link rel="stylesheet" href="/v0.3/css/prism.css"></head><body class="language-unknown"> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation" style="z-index: 200000;"><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.3/"><div> <img src="/v0.3/img/istio-logo.svg" alt="Istio Logo" height="54px"/> <span class="brand-name">Istioldie 0.3</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.3/about" >About</a></li><li><a href="/v0.3/blog" >Blog</a></li><li><a href="/v0.3/docs/welcome" class='current'>Docs</a></li><li><a href="/v0.3/help" >Help</a></li><li><a href="/v0.3/community" >Community</a></li><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 search-box" 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" class='active'><a href="/v0.3/docs/welcome/">Welcome</a></li><li role="presentation" ><a href="/v0.3/docs/concepts/">Concepts</a></li><li role="presentation" ><a href="/v0.3/docs/setup/">Setup</a></li><li role="presentation" ><a href="/v0.3/docs/tasks/">Tasks</a></li><li role="presentation" ><a href="/v0.3/docs/guides/">Guides</a></li><li role="presentation" ><a href="/v0.3/docs/reference/">Reference</a></li></ul></div></div></div><script src="/v0.3/js/navtree.min.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'>Welcome</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "contribute", "creating-a-pull-request.md", ], url: "/docs/welcome/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/welcome/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/welcome/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/welcome/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/welcome/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/welcome/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/welcome/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: [ "faq.md", ], url: "/docs/welcome/faq.html", title: "Frequently Asked Questions", order: 20, overview: "Frequently Asked Questions about Istio."}); docs.push({path: [ "feature-stages.md", ], url: "/docs/welcome/feature-stages.html", title: "Feature Status", order: 10, overview: "List of features and their release stages."}); docs.push({path: [ "glossary.md", ], url: "/docs/welcome/glossary.html", title: "Glossary", order: 30, overview: "A glossary of common Istio terms."}); docs.push({path: [ "index.md", ], url: "/docs/welcome/", title: "Welcome", order: 0, overview: "Istio documentation home page."}); docs.push({path: [ "notes", "0.1.md", ], url: "/docs/welcome/notes/0.1.html", title: "Istio 0.1", order: 100, overview: ""}); docs.push({path: [ "notes", "0.2.md", ], url: "/docs/welcome/notes/0.2.html", title: "Istio 0.2", order: 99, overview: ""}); docs.push({path: [ "notes", "0.3.md", ], url: "/docs/welcome/notes/0.3.html", title: "Istio 0.3", order: 98, overview: ""}); docs.push({path: [ "notes", "index.md", ], url: "/docs/welcome/notes/", title: "Release Notes", order: 5, overview: "What's been happening with Istio."}); 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.3/js/sidemenu.min.js"></script><footer><div class="container"><div class="row"><div class="col-lg-2 col-md-2 col-sm-2"></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.3/docs/welcome">Docs</a></li><li><a href="/v0.3/docs/concepts">Concepts</a></li><li><a href="/v0.3/docs/setup">Setup</a></li><li><a href="/v0.3/docs/tasks">Tasks</a></li><li><a href="/v0.3/docs/guides">Guides</a></li><li><a href="/v0.3/docs/reference">Reference</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.3/help">Help</a></li><li><a href="/v0.3/faq">FAQ</a></li><li><a href="/v0.3/glossary">Glossary</a></li><li><a href="/v0.3/troubleshooting">Troubleshooting</a></li><li><a href="/v0.3/bugs">Report Bugs</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/welcome/contribute/style-guide.md">Doc Bugs & Gaps</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/welcome/contribute/style-guide.md">Edit This Page</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li> <a class="header" href="/v0.3/community">Community</a></li><li> <a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank" rel="noopener">User</a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank" rel="noopener">Dev Mailing Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank" rel="noopener">Twitter</a></li><li><a href="https://stackoverflow.com/questions/tagged/istio" target="_blank" rel="noopener">Stack Overflow</a></li><li><a href="https://github.com/istio/community" target="_blank" rel="noopener">GitHub</a></li><li><a href="https://github.com/istio/community/blob/master/WORKING-GROUPS.md" target="_blank" rel="noopener">Working Groups</a></li></ul></div><div class="col-lg-1 col-md-1 col-sm-1"></div></div><div class="row"><p class="description small text-center"> Istio 0.3, Copyright © 2017 Istio Authors<br> Archived on 08-Dec-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.3/js/common.min.js"></script> <script src="/v0.3/js/search.js"></script> <script src="/v0.3/js/prism.min.js"></script></body></html>
|