Move Support topics. (#3108)
* Move Support topics. * Update stage-documentation-changes.md * Update stage-documentation-changes.md
This commit is contained in:
Steve Perry
@@ -2,97 +2,6 @@
|
||||
title: Creating a Documentation Pull Request
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
{% include support-content-moved.md %}
|
||||
|
||||
To contribute to the Kubernetes documentation, create a pull request against the
|
||||
[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"}
|
||||
repository. This page shows how to create a pull request.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
|
||||
1. Create a [GitHub account](https://github.com){: target="_blank"}.
|
||||
|
||||
1. Sign the
|
||||
[Linux Foundation Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}.
|
||||
|
||||
Documentation will be published under the [CC BY SA 4.0](https://github.com/kubernetes/kubernetes.github.io/blob/master/LICENSE) license.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## Creating a fork of the Kubernetes documentation repository
|
||||
|
||||
1. Go to the
|
||||
[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"}
|
||||
repository.
|
||||
|
||||
1. In the upper-right corner, click **Fork**. This creates a copy of the
|
||||
Kubernetes documentation repository in your GitHub account. The copy
|
||||
is called a *fork*.
|
||||
|
||||
## Making your changes
|
||||
|
||||
1. In your GitHub account, in your fork of the Kubernetes docs, create
|
||||
a new branch to use for your contribution.
|
||||
|
||||
1. In your new branch, make your changes and commit them. If you want to
|
||||
[write a new topic](/docs/contribute/write-new-topic/),
|
||||
choose the
|
||||
[page type](/docs/contribute/page-templates/)
|
||||
that is the best fit for your content.
|
||||
|
||||
## Submitting a pull request to the master branch (Current Release)
|
||||
|
||||
If you want your change to be published in the released version Kubernetes docs,
|
||||
create a pull request against the master branch of the Kubernetes
|
||||
documentation repository.
|
||||
|
||||
1. In your GitHub account, in your new branch, create a pull request
|
||||
against the master branch of the kubernetes/kubernetes.github.io
|
||||
repository. This opens a page that shows the status of your pull request.
|
||||
|
||||
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
|
||||
To the right of **deploy/netlify**, click **Details**. This opens a staging
|
||||
site where you can verify that your changes have rendered correctly.
|
||||
|
||||
1. During the next few days, check your pull request for reviewer comments.
|
||||
If needed, revise your pull request by committing changes to your
|
||||
new branch in your fork.
|
||||
|
||||
## Submitting a pull request to the <vnext> branch (Upcoming Release)
|
||||
|
||||
If your documentation change should not be released until the next release of
|
||||
the Kubernetes product, create a pull request against the <vnext> branch
|
||||
of the Kubernetes documentation repository. The <vnext> branch has the
|
||||
form `release-<version-number>`, for example release-1.5.
|
||||
|
||||
1. In your GitHub account, in your new branch, create a pull request
|
||||
against the <vnext> branch of the kubernetes/kubernetes.github.io
|
||||
repository. This opens a page that shows the status of your pull request.
|
||||
|
||||
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
|
||||
To the right of **deploy/netlify**, click **Details**. This opens a staging
|
||||
site where you can verify that your changes have rendered correctly.
|
||||
|
||||
1. During the next few days, check your pull request for reviewer comments.
|
||||
If needed, revise your pull request by committing changes to your
|
||||
new branch in your fork.
|
||||
|
||||
The staging site for the upcoming Kubernetes release is here:
|
||||
[http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/).
|
||||
The staging site reflects the current state of what's been merged in the
|
||||
release branch, or in other words, what the docs will look like for the
|
||||
next upcoming release. It's automatically updated as new PRs get merged.
|
||||
|
||||
{% 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).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/)
|
||||
|
||||
@@ -5,218 +5,6 @@ redirect_from:
|
||||
title: Using Page Templates
|
||||
---
|
||||
|
||||
<!--<html>
|
||||
<body>-->
|
||||
|
||||
<p>These page templates are available for writers who would like to contribute new topics to the Kubernetes docs:</p>
|
||||
|
||||
<ul>
|
||||
<li><a href="#task_template">Task</a></li>
|
||||
<li><a href="#tutorial_template">Tutorial</a></li>
|
||||
<li><a href="#concept_template">Concept</a></li>
|
||||
</ul>
|
||||
|
||||
<p>The page templates are in the <a href="https://github.com/kubernetes/kubernetes.github.io/tree/master/_includes/templates" target="_blank">_includes/templates</a> directory of the <a href="https://github.com/kubernetes/kubernetes.github.io">kubernetes.github.io</a> repository.
|
||||
|
||||
<h2 id="task_template">Task template</h2>
|
||||
|
||||
<p>A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.</p>
|
||||
|
||||
<p>To write a new task page, create a Markdown file in a subdirectory of the
|
||||
/docs/tasks directory. In your Markdown file, provide values for these
|
||||
variables, and then include templates/task.md:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>prerequisites - required</li>
|
||||
<li>steps - required</li>
|
||||
<li>discussion - optional</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>In the <code>steps</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed. Similarly, if you choose to have a <code>discussion</code> section,
|
||||
start the section with a level-two heading.</p>
|
||||
|
||||
<p>Here's an example of a Markdown file that uses the task template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Configuring This Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
* Do this.
|
||||
* Do this too.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
## Doing ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next. Possibly read this [related explanation](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture discussion %}
|
||||
## Understanding ...
|
||||
|
||||
Here's an interesting thing to know about the steps you just did.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related task](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the task template:</p>
|
||||
|
||||
<p><a href="/docs/tasks/access-kubernetes-api/http-proxy-access-api">Using an HTTP Proxy to Access the Kubernetes API</a></p>
|
||||
|
||||
<h2 id="tutorial_template">Tutorial template</h2>
|
||||
|
||||
<p>A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
<p>To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
/docs/tutorials directory. In your Markdown file, provide values for these
|
||||
variables, and then include templates/tutorial.md:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>prerequisites - required</li>
|
||||
<li>objectives - required</li>
|
||||
<li>lessoncontent - required</li>
|
||||
<li>cleanup - optional</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>In the <code>lessoncontent</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed.
|
||||
|
||||
<p>Here's an example of a Markdown file that uses the tutorial template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Running a Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
* Do this.
|
||||
* Do this too.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture objectives %}
|
||||
* Learn this.
|
||||
* Build this.
|
||||
* Run this.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture lessoncontent %}
|
||||
## Building ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next. Possibly read this [related explanation](...).
|
||||
|
||||
## Running ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next.
|
||||
|
||||
## Understanding the code
|
||||
Here's something interesting about the code you ran in the preceding steps.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture cleanup %}
|
||||
* Delete this.
|
||||
* Stop this.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related tutorial](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/tutorial.md %}
|
||||
</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the tutorial template:</p>
|
||||
|
||||
<p><a href="/docs/tutorials/stateless-application/run-stateless-application-deployment/">Running a Stateless Application Using a Deployment</a></p>
|
||||
|
||||
<h2 id="concept_template">Concept template</h2>
|
||||
|
||||
<p>A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
<p>To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
/docs/concepts directory. In your Markdown file, provide values for these
|
||||
variables, and then include templates/concept.md:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>body - required</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>In the <code>body</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed.
|
||||
|
||||
<p>Here's an example of a page that uses the concept template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Understanding this Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page explains ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
## Understanding ...
|
||||
|
||||
Kubernetes provides ...
|
||||
|
||||
## Using ...
|
||||
|
||||
To use ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related task](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the concept template:</p>
|
||||
|
||||
<p><a href="/docs/concepts/object-metadata/annotations">Annotations</a></p>
|
||||
|
||||
<!--</body>
|
||||
</html>-->
|
||||
{% include support-content-moved.md %}
|
||||
|
||||
[Using Page Templates](/docs/home/contribute/page-template/)
|
||||
|
||||
@@ -2,72 +2,6 @@
|
||||
title: Reviewing Documentation Issues
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
{% include support-content-moved.md %}
|
||||
|
||||
This page explains how documentation issues are reviewed and prioritized for the [kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} repository. The purpose is to provide a way to organize issues and make it easier to contribute to Kubernetes documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
|
||||
## Categorizing issues
|
||||
Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesn't have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesn't fit into any of the categories below) you should close the issue with a comment explaining why it is being closed.
|
||||
|
||||
### Needs Clarification
|
||||
* Issues that need more information from the original submitter to make them actionable. Issues with this label that aren't followed up within a week may be closed.
|
||||
|
||||
### Actionable
|
||||
* Issues that can be worked on with current information (or may need a comment to explain what needs to be done to make it more clear)
|
||||
* Allows contributors to have easy to find issues to work on
|
||||
|
||||
|
||||
### Needs Tech Review
|
||||
* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a subject matter expert needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant)
|
||||
* Promotes transparency about level of work needed for the issue and that issue is in progress
|
||||
|
||||
### Needs Docs Review
|
||||
* Issues that are suggestions for better processes or site improvements that require community agreement to be implemented
|
||||
* Topics can be brought to SIG meetings as agenda items
|
||||
|
||||
### Needs UX Review
|
||||
* Issues that are suggestions for improving the user interface of the site.
|
||||
* Fixing broken site elements.
|
||||
|
||||
|
||||
## Prioritizing Issues
|
||||
The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change.
|
||||
|
||||
### P1
|
||||
* Major content errors affecting more than 1 page
|
||||
* Broken code sample on a heavily trafficked page
|
||||
* Errors on a “getting started” page
|
||||
* Well known or highly publicized customer pain points
|
||||
* Automation issues
|
||||
|
||||
### P2
|
||||
* Default for all new issues
|
||||
* Broken code for sample that is not heavily used
|
||||
* Minor content issues in a heavily trafficked page
|
||||
* Major content issues on a lower-trafficked page
|
||||
|
||||
### P3
|
||||
* Typos and broken anchor links
|
||||
|
||||
## Handling special issue types
|
||||
|
||||
### Duplicate issues
|
||||
If a single problem has one or more issues open for it, the problem should be consolodated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem.
|
||||
|
||||
### Dead link issues
|
||||
Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3.
|
||||
|
||||
{% 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).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
[Reviewing Documentation Issues](/docs/home/contribute/review-issues/)
|
||||
|
||||
@@ -2,108 +2,6 @@
|
||||
title: Staging Your Documentation Changes
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to stage content that you want to contribute
|
||||
to the Kubernetes documentation.
|
||||
{% endcapture %}
|
||||
{% include support-content-moved.md %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## Staging from your GitHub account
|
||||
|
||||
GitHub provides staging of content in your master branch. Note that you
|
||||
might not want to merge your changes into your master branch. If that is
|
||||
the case, choose another option for staging your content.
|
||||
|
||||
1. In your GitHub account, in your fork, merge your changes into
|
||||
the master branch.
|
||||
|
||||
1. Change the name of your repository to `<your-username>.github.io`, where
|
||||
`<your-username>` is the username of your GitHub account.
|
||||
|
||||
1. Delete the `CNAME` file.
|
||||
|
||||
1. View your staged content at this URL:
|
||||
|
||||
https://<your-username>.github.io
|
||||
|
||||
## Staging a pull request
|
||||
|
||||
When you create a pull request, either against the master or <vnext>
|
||||
branch, your changes are staged in a custom subdomain on Netlify so that
|
||||
you can see your changes in rendered form before the pull request is merged.
|
||||
|
||||
1. In your GitHub account, in your new branch, submit a pull request to the
|
||||
kubernetes/kubernetes.github.io repository. This opens a page that shows the
|
||||
status of your pull request.
|
||||
|
||||
1. Scroll down to the list of automated checks. Click **Show all checks**.
|
||||
Wait for the **deploy/netlify** check to complete. To the right of
|
||||
**deploy/netlify**, click **Details**. This opens a staging site where you
|
||||
can see your changes.
|
||||
|
||||
## Staging locally using Docker
|
||||
|
||||
You can use the k8sdocs Docker image to run a local staging server. If you're
|
||||
interested, you can view the
|
||||
[Dockerfile](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile){: target="_blank"}
|
||||
for this image.
|
||||
|
||||
1. Install Docker if you don't already have it.
|
||||
|
||||
1. Clone your fork to your local development machine.
|
||||
|
||||
1. In the root of your cloned repository, enter this command to start a local
|
||||
web server:
|
||||
|
||||
docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.1
|
||||
|
||||
1. View your staged content at
|
||||
[http://localhost:4000](http://localhost:4000){: target="_blank"}.
|
||||
|
||||
## Staging locally without Docker
|
||||
|
||||
1. [Install Ruby 2.2 or later](https://www.ruby-lang.org){: target="_blank"}.
|
||||
|
||||
1. [Install RubyGems](https://rubygems.org){: target="_blank"}.
|
||||
|
||||
1. Verify that Ruby and RubyGems are installed:
|
||||
|
||||
gem --version
|
||||
|
||||
1. Install the GitHub Pages package, which includes Jekyll:
|
||||
|
||||
gem install github-pages
|
||||
|
||||
1. Clone your fork to your local development machine.
|
||||
|
||||
1. In the root of your cloned repository, enter this command to start a local
|
||||
web server:
|
||||
|
||||
jekyll serve
|
||||
|
||||
1. View your staged content at
|
||||
[http://localhost:4000](http://localhost:4000){: target="_blank"}.
|
||||
|
||||
<i>NOTE: If you do not want Jekyll to interfere with your other globally installed gems, you can use `bundler`:</i>
|
||||
|
||||
gem install bundler
|
||||
bundle install
|
||||
bundler exec jekyll serve
|
||||
|
||||
<i> Regardless of whether you use `bundler` or not, your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000)</i>
|
||||
|
||||
{% 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 [creating a pull request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
[Staging Your Documentation Changes](/docs/home/contribute/stage-documentation-changes/)
|
||||
|
||||
@@ -2,235 +2,6 @@
|
||||
title: Documentation Style Guide
|
||||
---
|
||||
|
||||
{% 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.
|
||||
{% include support-content-moved.md %}
|
||||
|
||||
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
|
||||
|
||||
### 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
|
||||
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. Tell the reader what a placeholder
|
||||
represents.
|
||||
|
||||
1. Display information about a pod:
|
||||
|
||||
kubectl describe pod <pod-name>
|
||||
|
||||
where `<pod-name>` is the name of one of your pods.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
|
||||
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use italics to define or introduce new terms
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
|
||||
<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
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
|
||||
<tr><td>Open the <code>/_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr>
|
||||
</table>
|
||||
|
||||
## Inline code formatting
|
||||
|
||||
### 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 (`).
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
### Use code style for object field names
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
### Use normal style for string and integer field values
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
|
||||
<tr><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></tr>
|
||||
</table>
|
||||
|
||||
## Code snippet formatting
|
||||
|
||||
### 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
|
||||
|
||||
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.
|
||||
|
||||
<table>
|
||||
<tr><th>Term</th><th>Useage</th></tr>
|
||||
<tr><td>TBD</td><td>TBD</td></tr>
|
||||
</table>{% endcomment %}
|
||||
|
||||
|
||||
## Content best practices
|
||||
|
||||
This section contains suggested best practices for clear, concise, and consistent content.
|
||||
|
||||
### Use present tense
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
|
||||
</table>
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct
|
||||
meaning.
|
||||
|
||||
### Use active voice
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
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."
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
|
||||
</table>
|
||||
|
||||
### Address the reader as "you"
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
## 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.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
### Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
### 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.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
{% 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 %}
|
||||
[Documentation Style Guide](/docs/home/contribute/style-guide/)
|
||||
|
||||
@@ -2,142 +2,6 @@
|
||||
title: Writing a New Topic
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to create a new topic for the Kubernetes docs.
|
||||
{% endcapture %}
|
||||
{% include support-content-moved.md %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## Choosing a page type
|
||||
|
||||
As you prepare to write a new topic, think about which of these page types
|
||||
is the best fit for your content:
|
||||
|
||||
<table>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tutorial</td>
|
||||
<td>A tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial page has several sections, each of which has a sequence of steps. For example, a tutorial might provide a walkthrough of a code sample that illustrates a certain feature of Kubernetes. Tutorials can include surface-level explanations, but should link to related concept topics for deep explanations.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
Each page type has a
|
||||
[template](/docs/contribute/page-templates/)
|
||||
that you can use as you write your topic.
|
||||
Using templates helps ensure consistency among topics of a given type.
|
||||
|
||||
## Choosing a title and filename
|
||||
|
||||
Choose a title that has the keywords you want search engines to find.
|
||||
Create a filename that uses the words in your title separated by hyphens.
|
||||
For example, the topic with title
|
||||
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
|
||||
has filename `http-proxy-access-api.md`. You don't need to put
|
||||
"kubernetes" in the filename, because "kubernetes" is already in the
|
||||
URL for the topic, for example:
|
||||
|
||||
http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
|
||||
|
||||
## Adding the topic title to the front matter
|
||||
|
||||
In your topic, put a `title` field in the
|
||||
[front matter](https://jekyllrb.com/docs/frontmatter/).
|
||||
The front matter is the YAML block that is between the
|
||||
triple-dashed lines at the top of the page. Here's an example:
|
||||
|
||||
---
|
||||
title: Using an HTTP Proxy to Access the Kubernetes API
|
||||
---
|
||||
|
||||
## Choosing a directory
|
||||
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
|
||||
* /docs/tasks/
|
||||
* /docs/tutorials/
|
||||
* /docs/concepts/
|
||||
|
||||
You can put your file in an existing subdirectory, or you can create a new
|
||||
subdirectory.
|
||||
|
||||
## Creating an entry in the table of contents
|
||||
|
||||
Depending page type, create an entry in one of these files:
|
||||
|
||||
* /_data/tasks.yaml
|
||||
* /_data/tutorials.yaml
|
||||
* /_data/concepts.yaml
|
||||
|
||||
Here's an example of an entry in /_data/tasks.yaml:
|
||||
|
||||
- docs/tasks/configure-pod-container/configure-volume-storage.md
|
||||
|
||||
## Including code from another file
|
||||
|
||||
To include a code file in your topic, place the code file in the Kubernetes
|
||||
documentation repository, preferably in the same directory as your topic
|
||||
file. In your topic file, use the `include` tag:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="/<PATHFROMROOT>" %}</pre>
|
||||
|
||||
where:
|
||||
|
||||
* `<LEXERVALUE>` is the language in which the file was written. This must be
|
||||
[a value supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
|
||||
* `<RELATIVEPATH>` is the path to the file you're including, relative to the current file, for example, `gce-volume.yaml`.
|
||||
* `<PATHFROMROOT>` is the path to the file relative to root, for example, `docs/tutorials/stateful-application/gce-volume.yaml`.
|
||||
|
||||
Here's an example of using the `include` tag:
|
||||
|
||||
<pre>{% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %}</pre>
|
||||
|
||||
## Showing how to create an API object from a configuration file
|
||||
|
||||
If you need to show the reader how to create an API object based on a
|
||||
configuration file, place the configuration file in the Kubernetes documentation
|
||||
repository, preferably in the same directory as your topic file.
|
||||
|
||||
In your topic, show this command:
|
||||
|
||||
kubectl create -f http://k8s.io/<PATHFROMROOT>
|
||||
|
||||
where `<PATHFROMROOT>` is the path to the configuration file relative to root,
|
||||
for example, `docs/tutorials/stateful-application/gce-volume.yaml`.
|
||||
|
||||
Here's an example of a command that creates an API object from a configuration file:
|
||||
|
||||
kubectl create -f http://k8s.io/docs/tutorials/stateful-application/gce-volume.yaml
|
||||
|
||||
For an example of a topic that uses this technique, see
|
||||
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).
|
||||
|
||||
## Adding images to a topic
|
||||
|
||||
Put image files in the `/images` directory. The preferred
|
||||
image format is SVG.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* 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/task.md %}
|
||||
[Writing a New Topic](/docs/home/contribute/write-new-topic/)
|
||||
|
||||
Reference in New Issue
Block a user