Merge remote-tracking branch 'upstream/master'

2016-12-05 10:19:54 -05:00
parent 18252f80e4 f5c876845d
commit 3e6493cf46
28 changed files with 634 additions and 1093 deletions
@@ -1,4 +1,7 @@
 ---
+redirect_from:
+  - /docs/templatedemos/
+  - /docs/templatedemos.html
 ---

 <!--<html>
@@ -14,20 +14,31 @@ docs, follow the instructions on

 {% capture body %}

-## Documentation formatting standards
+### Documentation formatting standards

-### Capitalize API objects
+#### Use Camel Case for API objects

-Capitalize the names of API objects. Refer to API objects without saying
-"object."
+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
+[camel case](https://en.wikipedia.org/wiki/Camel_case).
+
+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.

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
  <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>
 </table>

-### Use angle brackets for placeholders
+#### Use angle brackets for placeholders

 Use angle brackets for placeholders. Tell the reader what a placeholder
 represents.
@@ -38,7 +49,7 @@ represents.

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

-### Use bold for user interface elements
+#### Use bold for user interface elements

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
@@ -46,7 +57,7 @@ represents.
  <tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
 </table>

-### Use italics to define or introduce new terms
+#### Use italics to define or introduce new terms

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
@@ -54,7 +65,7 @@ represents.
  <tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
 </table>

-### Use code style for filenames, directories, and paths
+#### Use code style for filenames, directories, and paths

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
@@ -63,9 +74,9 @@ represents.
  <tr><td>Open the <code>/_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr>
 </table>

-## Code snippet formatting
+### Code snippet formatting

-### Use code style for inline code and commands
+#### Use code style for inline code and commands

 For inline code in an HTML document, use the `<code>` tag. In a Markdown
 document, use the backtick (`).
@@ -76,14 +87,14 @@ document, use the backtick (`).
  <tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
 </table>

-### Don't include the command prompt
+#### Don't include the command prompt

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
 </table>

-### Separate commands from output
+#### Separate commands from output

 Verify that the pod is running on your chosen node:

@@ -105,11 +116,11 @@ A list of Kubernetes-specific terms and words to be used consistently across the
 </table>{% endcomment %}


-## Content best practices
+### Content best practices

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

-### Use present tense
+#### Use present tense

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
@@ -119,7 +130,7 @@ This section contains suggested best practices for clear, concise, and consisten
 Exception: Use future or past tense if it is required to convey the correct
 meaning.

-### Use active voice
+#### Use active voice

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
@@ -129,7 +140,7 @@ meaning.

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

-### Use simple and direct language
+#### Use simple and direct language

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

@@ -141,7 +152,7 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying

 </table>

-### Address the reader as "you"
+#### Address the reader as "you"

 <table>
  <tr><th>Do</th><th>Don't</th></tr>
@@ -149,9 +160,9 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
    <tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
 </table>

-## Patterns to avoid
+### Patterns to avoid

-### Avoid using "we"
+#### 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.
@@ -163,7 +174,7 @@ whether they're part of the "we" you're describing.
  <tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr>
 </table>

-### Avoid jargon and idioms
+#### Avoid jargon and idioms

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

@@ -173,13 +184,13 @@ Some readers speak English as a second language. Avoid jargon and idioms to help
    <tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
 </table>

-### Avoid statements about the future
+#### 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 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.