From 31b8ccb76d0182378e4a9c227ad805c89c641a54 Mon Sep 17 00:00:00 2001 From: Anthony Yeh Date: Wed, 30 Nov 2016 12:48:15 -0800 Subject: [PATCH] Fix TOC in Documentation Style Guide "What's next" was listed underneath "Patterns to avoid" because the template hard-codes the heading depth. Increase depth of all other headings by 1 to match the template's expectations. --- docs/contribute/style-guide.md | 40 +++++++++++++++++----------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/contribute/style-guide.md b/docs/contribute/style-guide.md index 1a23c7fac3..9d65dbda9a 100644 --- a/docs/contribute/style-guide.md +++ b/docs/contribute/style-guide.md @@ -14,9 +14,9 @@ docs, follow the instructions on {% capture body %} -## Documentation formatting standards +### Documentation formatting standards -### Use Camel Case for API objects +#### Use Camel Case 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 @@ -38,7 +38,7 @@ leads to an awkward construction. The two ContainerStateTerminated objects ...The two ContainerStateTerminateds ... -### Use angle brackets for placeholders +#### Use angle brackets for placeholders Use angle brackets for placeholders. Tell the reader what a placeholder represents. @@ -49,7 +49,7 @@ represents. where `` is the name of one of your pods. -### Use bold for user interface elements +#### Use bold for user interface elements @@ -57,7 +57,7 @@ represents.
DoDon't
Select Other.Select 'Other'.
-### Use italics to define or introduce new terms +#### Use italics to define or introduce new terms @@ -65,7 +65,7 @@ represents.
DoDon't
These components form the control plane.These components form the control plane.
-### Use code style for filenames, directories, and paths +#### Use code style for filenames, directories, and paths @@ -74,9 +74,9 @@ represents.
DoDon't
Open the /_data/concepts.yaml file.Open the /_data/concepts.yaml file.
-## 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 `` tag. In a Markdown document, use the backtick (`). @@ -87,14 +87,14 @@ document, use the backtick (`). The kubectl run command creates a Deployment.The "kubectl run" command creates a Deployment. -### Don't include the command prompt +#### Don't include the command prompt
DoDon't
kubectl get pods$ kubectl get pods
-### Separate commands from output +#### Separate commands from output Verify that the pod is running on your chosen node: @@ -116,11 +116,11 @@ A list of Kubernetes-specific terms and words to be used consistently across the {% 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 @@ -130,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
DoDon't
@@ -140,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." @@ -152,7 +152,7 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
DoDon't
-### Address the reader as "you" +#### Address the reader as "you" @@ -160,9 +160,9 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
DoDon't
In the preceding output, you can see...In the preceding output, we can see ...
-## 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. @@ -174,7 +174,7 @@ whether they're part of the "we" you're describing. This page teaches you how to use pods.In this page, we are going to learn about pods. -### 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. @@ -184,13 +184,13 @@ Some readers speak English as a second language. Avoid jargon and idioms to help Create a new cluster.Turn up a new cluster. -### 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.