From 0bd5651d4f529f7bc707ce3de6ea4a475ed72199 Mon Sep 17 00:00:00 2001 From: David Kirstein Date: Thu, 10 Nov 2016 08:19:22 +0100 Subject: [PATCH 1/4] Fix typo in working-with-resources.md mode -> more --- docs/user-guide/working-with-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/working-with-resources.md b/docs/user-guide/working-with-resources.md index 5b300ee6bd..b5b0f8f862 100644 --- a/docs/user-guide/working-with-resources.md +++ b/docs/user-guide/working-with-resources.md @@ -46,7 +46,7 @@ The system adds fields in several ways: - Some fields are added synchronously with creation of the resource and some are set asynchronously. - For example: `metadata.uid` is set synchronously. (Read more about [metadata](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#metadata)). - - For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read mode about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization) ). + - For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read more about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization) ). - Some fields are set to default values. Some defaults vary by cluster and some are fixed for the API at a certain version. (Read more about [defaulting](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#defaulting)). - For example, `spec.containers[0].imagePullPolicy` always defaults to `IfNotPresent` in api v1. - For example, `spec.containers[0].resources.limits.cpu` may be defaulted to `100m` on some clusters, to some other value on others, and not defaulted at all on others. From e745b0480157ae4ce17b534b107d21d7552da17c Mon Sep 17 00:00:00 2001 From: David Kirstein Date: Thu, 10 Nov 2016 08:27:09 +0100 Subject: [PATCH 2/4] remove extra space in working-with-resources.md --- docs/user-guide/working-with-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/working-with-resources.md b/docs/user-guide/working-with-resources.md index b5b0f8f862..d2aeeb621e 100644 --- a/docs/user-guide/working-with-resources.md +++ b/docs/user-guide/working-with-resources.md @@ -46,7 +46,7 @@ The system adds fields in several ways: - Some fields are added synchronously with creation of the resource and some are set asynchronously. - For example: `metadata.uid` is set synchronously. (Read more about [metadata](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#metadata)). - - For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read more about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization) ). + - For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read more about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization)). - Some fields are set to default values. Some defaults vary by cluster and some are fixed for the API at a certain version. (Read more about [defaulting](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#defaulting)). - For example, `spec.containers[0].imagePullPolicy` always defaults to `IfNotPresent` in api v1. - For example, `spec.containers[0].resources.limits.cpu` may be defaulted to `100m` on some clusters, to some other value on others, and not defaulted at all on others. From e3c87235a548a6a698f6dc73a40485f691fefd78 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Mon, 14 Nov 2016 10:08:00 -0800 Subject: [PATCH 3/4] Fix example test failure: rename ScheduledJob to CronJob --- test/examples_test.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/test/examples_test.go b/test/examples_test.go index 1853cdaf0a..7e5660c4f9 100644 --- a/test/examples_test.go +++ b/test/examples_test.go @@ -127,11 +127,11 @@ func validateObject(obj runtime.Object) (errors field.ErrorList) { t.Namespace = api.NamespaceDefault } errors = expvalidation.ValidateDaemonSet(t) - case *batch.ScheduledJob: + case *batch.CronJob: if t.Namespace == "" { t.Namespace = api.NamespaceDefault } - errors = batch_validation.ValidateScheduledJob(t) + errors = batch_validation.ValidateCronJob(t) default: errors = field.ErrorList{} errors = append(errors, field.InternalError(field.NewPath(""), fmt.Errorf("no validation defined for %#v", obj))) @@ -242,7 +242,7 @@ func TestExampleObjectSchemas(t *testing.T) { "redis-resource-deployment": &extensions.Deployment{}, "redis-secret-deployment": &extensions.Deployment{}, "run-my-nginx": &extensions.Deployment{}, - "sj": &batch.ScheduledJob{}, + "sj": &batch.CronJob{}, }, "../docs/admin": { "daemon": &extensions.DaemonSet{}, @@ -272,7 +272,7 @@ func TestExampleObjectSchemas(t *testing.T) { "../docs/user-guide/node-selection": { "pod": &api.Pod{}, "pod-with-node-affinity": &api.Pod{}, - "pod-with-pod-affinity": &api.Pod{}, + "pod-with-pod-affinity": &api.Pod{}, }, "../docs/admin/resourcequota": { "best-effort": &api.ResourceQuota{}, From 7f8a38b7432a059ee9b0116469fadeca6ca9b017 Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Tue, 15 Nov 2016 12:26:42 -0800 Subject: [PATCH 4/4] Write style guide. (#1619) --- _data/support.yml | 2 + docs/contribute/style-guide.md | 203 +++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 docs/contribute/style-guide.md diff --git a/_data/support.yml b/_data/support.yml index e280c827d7..1b8e80699a 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -14,6 +14,8 @@ toc: path: /docs/contribute/stage-documentation-changes/ - title: Using Page Templates path: /docs/contribute/page-templates/ + - title: Documentation Style Guide + path: /docs/contribute/style-guide/ - title: Troubleshooting section: diff --git a/docs/contribute/style-guide.md b/docs/contribute/style-guide.md new file mode 100644 index 0000000000..219d62560d --- /dev/null +++ b/docs/contribute/style-guide.md @@ -0,0 +1,203 @@ +--- +--- + +{% capture overview %} +This page gives writing style guidelines for the Kubernetes documentation. +These are guidelines, not rules. Use your best judgment, and feel free to +propose changes to this document in a pull request. + +For additional information on creating new content for the Kubernetes +docs, follow the instructions on +[using page templates](/docs/contribute/page-templates/) and +[creating a documentation pull request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% capture body %} + +## Documentation formatting standards + +### Capitalize API objects + +Capitalize the names of API objects. Refer to API objects without saying +"object." + + + + + +
DoDon't
The Pod has two Containers.The pod has two containers.
The Deployment is responsible for ...The Deployment object is responsible for ...
+ +### Use angle brackets for placeholders + +Use angle brackets for placeholders. Tell the reader what a placeholder +represents. + +1. Display information about a pod: + + kubectl describe pod + + where `` is the name of one of your pods. + +### Use bold for user interface elements + + + + + +
DoDon't
Click Fork.Click "Fork".
Select Other.Select 'Other'.
+ +### Use italics to define or introduce new terms + + + + + +
DoDon't
A cluster is a set of nodes ...A "cluster" is a set of nodes ...
These components form the control plane.These components form the control plane.
+ +### Use code style for filenames, directories, and paths + + + + + + +
DoDon't
Open the envars.yaml file.Open the envars.yaml file.
Go to the /docs/tutorials directory.Go to the /docs/tutorials directory.
Open the /_data/concepts.yaml file.Open the /_data/concepts.yaml file.
+ +## Code snippet formatting + +### 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 (`). + + + + + +
DoDon't
Set the value of the replicas field in the configuration file.Set the value of the "replicas" field in the configuration file.
The kubectl run command creates a Deployment.The "kubectl run" command creates a Deployment.
+ +### Don't include the command prompt + + + + +
DoDon't
kubectl get pods$ kubectl get pods
+ +### Separate commands from output + +Verify that the pod is running on your chosen node: + + kubectl get pods --output=wide + +The output is similar to this: + + NAME READY STATUS RESTARTS AGE IP NODE + nginx 1/1 Running 0 13s 10.200.0.4 worker0 + + +{% comment %}## Kubernetes.io word list + +A list of Kubernetes-specific terms and words to be used consistently across the site. + + + + +
TermUseage
TBDTBD
{% endcomment %} + + +## Content best practices + +This section contains suggested best practices for clear, concise, and consistent content. + +### Use present tense + + + + +
DoDon't
This command starts a proxy.This command will start a proxy.
+ +Exception: Use future or past tense if it is required to convey the correct +meaning. + +### Use active voice + + + + + +
DoDon't
You can explore the API using a browser.The API can be explored using a browser.
The YAML file specifies the replica count.The replica count is specified in the YAML file.
+ +Exception: Use passive voice if active voice leads to an awkward construction. + +### Use simple and direct language + +Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." + + + + + + + +
DoDon't
To create a ReplicaSet, ...In order to create a ReplicaSet, ...
See the configuration file.Please see the configuration file.
View the Pods.With this next command, we'll view the Pods.
+ +### Address the reader as "you" + + + + + +
DoDon't
You can create a Deployment by ...We'll create a Deployment by ...
In the preceding output, you can see...In the preceding output, we can see ...
+ +## Patterns to avoid + +### 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. + + + + + + +
DoDon't
Version 1.4 includes ...In version 1.4, we have added ...
Kubernetes provides a new feature for ...We provide a new feature ...
This page teaches you how to use pods.In this page, we are going to learn about pods.
+ +### Avoid jargon and idioms + +Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier. + + + + + +
DoDon't
Internally, ...Under the hood, ...
Create a new cluster.Turn up a new cluster.
+ +### 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 words like "currently" and "new." A feature that is new today might not be +considered new in a few months. + + + + + +
DoDon't
In version 1.4, ...In the current version, ...
The Federation feature provides ...The new Federation feature provides ...
+ +{% endcapture %} + + +{% capture whatsnext %} +* Learn about [writing a new topic](/docs/contribute/write-new-topic/). +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [staging your changes](/docs/contribute/stage-documentation-changes/) +* Learn about [creating a pull request](/docs/contribute/create-pull-request/). +{% endcapture %} + +{% include templates/concept.md %}