whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Versioning howto (#7400)

Browse Source 
* whitespace cleanup

* adding word list since it keeps appearing in reviews...

* initial draft based on feb13,2018 docs meeting conversation

* nits
This commit is contained in:
Joseph Heck
2018-02-13 16:39:51 -08:00
committed by k8s-ci-robot
parent c5a897c94e
commit ef6c7d8517
1 changed files with 60 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/home/contribute/style-guide.md
+60 -30
View File
@@ -18,12 +18,10 @@ docs, follow the instructions on
**Note:** Kubernetes documentation uses [GitHub Flavored Markdown](https://github.github.com/gfm/).
{: .note}
## Language
Kubernetes documentation uses US English.
## Documentation formatting standards
### Use camel case for API objects
@@ -144,24 +142,56 @@ The output is similar to this:
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
### Versioning Kubernetes examples
{% comment %}## Kubernetes.io word list
Code examples and configuration examples that include version information should be consistent with the accompanying text. Identify the Kubernetes version in the **Before you begin** section.
To specify the Kubernetes version for a task or tutorial page:
- Include `min-kubernetes-server-version` in the front matter of the page.
- In the **Before you begin** section, use `{{ "{% include tasks-tutorial-prereqs.md "}} %}`.
If the example YAML is in a standalone file, find and review the topics that include it as a reference.
Verify that any topics using the standalone YAML have the appropriate version information defined.
If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.
For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:
```yaml
---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---
```
In code and configuration examples, do not include comments about alternative versions.
Be careful to not include incorrect statements in your examples as comments, such as:
```yaml
apiVersion: v1 # earlier versions use...
kind: Pod
...
```
## Kubernetes.io word list
A list of Kubernetes-specific terms and words to be used consistently across the site.
<table>
<tr><th>Term</th><th>Usage</th></tr>
<tr><td>TBD</td><td>TBD</td></tr>
</table>{% endcomment %}
<tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
<tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
<tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
</table>
## Callout Formatting
Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: **Note:** {: .note}, **Caution:** {: .caution}, and **Warning:** {: .warning}.
Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: **Note:** {: .note}, **Caution:** {: .caution}, and **Warning:** {: .warning}.
1. Start each callout with the appropriate prefix.
2. Use the following syntax to apply a style:
**Note:** The prefix you use is the same text you use in the tag.
**Note:** The prefix you use is the same text you use in the tag.
{: .note} <!-- This tag must appear on a new line. -->
The output is:
@@ -171,11 +201,11 @@ The output is:
### Note
Use {: .note} to highlight a tip or a piece of information that may be helpful to know.
Use {: .note} to highlight a tip or a piece of information that may be helpful to know.
For example:
**Note:** You can _still_ use Markdown inside these callouts.
**Note:** You can _still_ use Markdown inside these callouts.
{: .note}
The output is:
@@ -185,16 +215,16 @@ The output is:
### Caution
Use {: .caution} to call attention to an important piece of information to avoid pitfalls.
Use {: .caution} to call attention to an important piece of information to avoid pitfalls.
For example:
**Caution:** The callout style only applies to the line directly above the tag.
**Caution:** The callout style only applies to the line directly above the tag.
{: .caution}
The output is:
**Caution:** The callout style only applies to the line directly above the tag.
**Caution:** The callout style only applies to the line directly above the tag.
{: .caution}
### Warning
@@ -203,12 +233,12 @@ Use {: .warning} to indicate danger or a piece of information that is crucial to
For example:
**Warning:** Beware.
**Warning:** Beware.
{: .warning}
The output is:
**Warning:** Beware.
**Warning:** Beware.
{: .warning}
## Common Callout Issues
@@ -234,14 +264,14 @@ The output is:
**Note:** This is my note. Use `<br/>` to create multiple lines. <br/> <br/> You can still use _Markdown_ to **format** text!
{: .note}
Typing multiple lines does **not** work. The callout style only applies to the line directly above the tag.
Typing multiple lines does **not** work. The callout style only applies to the line directly above the tag.
**Note:** This is my note.
**Note:** This is my note.
I didn't read the style guide.
{: .note}
**Note:** This is my note.
**Note:** This is my note.
I didn't read the style guide.
{: .note}
@@ -253,25 +283,24 @@ Callouts will interrupt numbered lists unless you indent three spaces before the
For example:
1. Preheat oven to 350˚F
1. Prepare the batter, and pour into springform pan.
**Note:** Grease the pan for best results.
**Note:** Grease the pan for best results.
{: .note}
1. Bake for 20-25 minutes or until set.
The output is:
1. Preheat oven to 350˚F
1. Prepare the batter, and pour into springform pan.
**Note:** Grease the pan for best results.
{: .note}
1. Bake for 20-25 minutes or until set.
1. Prepare the batter, and pour into springform pan.
**Note:** Grease the pan for best results.
{: .note}
1. Bake for 20-25 minutes or until set.
## Content best practices
@@ -372,12 +401,13 @@ considered new in a few months.
{% endcapture %}
{% capture whatsnext %}
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{% endcapture %}
{% include templates/concept.md %}