Merge pull request #2303 from steveperry-53/contribution-guide

Update headings and guidance about headings.
2017-01-19 14:43:52 -08:00 · 2017-01-19 14:43:52 -08:00 · 1ea84ea5ba
parent 52a1b9f7ab 01d3ade539
commit 1ea84ea5ba
7 changed files with 89 additions and 77 deletions
--- a/_data/support.yml
+++ b/_data/support.yml
@ -3,17 +3,6 @@ abstract: "Troubleshooting resources, frequently asked questions, and community
 toc:
 - docs/troubleshooting.md

- title: Contributing to the Kubernetes Docs
-  section:
-  - editdocs.md
-  - docs/contribute/create-pull-request.md
-  - docs/contribute/write-new-topic.md
-  - docs/contribute/stage-documentation-changes.md
-  - docs/contribute/page-templates.md
-  - docs/contribute/review-issues.md
-  - docs/contribute/style-guide.md
-
-
 - title: Troubleshooting
  section:
  - docs/user-guide/debugging-pods-and-replication-controllers.md
@ -31,6 +20,16 @@ toc:
  - title: Services FAQ
    path: https://github.com/kubernetes/kubernetes/wiki/Services-FAQ/

+- title: Contributing to the Kubernetes Docs
+  section:
+  - editdocs.md
+  - docs/contribute/create-pull-request.md
+  - docs/contribute/write-new-topic.md
+  - docs/contribute/stage-documentation-changes.md
+  - docs/contribute/page-templates.md
+  - docs/contribute/review-issues.md
+  - docs/contribute/style-guide.md
+
 - title: Other Resources
  section:
  - title: Kubernetes Issue Tracker on GitHub
@ -40,6 +39,6 @@ toc:
    path: https://github.com/kubernetes/kubernetes/releases/
  - title: Release Roadmap
    path: https://github.com/kubernetes/kubernetes/milestones/
-  
+
 - title: Deprecation Policy
  path: /docs/deprecation-policy.md
--- a/docs/contribute/create-pull-request.md
+++ b/docs/contribute/create-pull-request.md
@ -23,7 +23,7 @@ Documentation will be published under the [CC BY SA 4.0](https://github.com/kube

 {% capture steps %}

-### Creating a fork of the Kubernetes documentation repository
+## 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"}
@ -33,18 +33,18 @@ repository.
 Kubernetes documentation repository in your GitHub account. The copy
 is called a *fork*.

-### Making your changes
+## 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 
+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)
+## 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
@ -62,7 +62,7 @@ site where you can verify that your changes have rendered correctly.
 If needed, revise your pull request by committing changes to your
 new branch in your fork.

-### Submitting a pull request to the &lt;vnext&gt; branch (Upcoming Release)
+## Submitting a pull request to the &lt;vnext&gt; 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 &lt;vnext&gt; branch
--- a/docs/contribute/page-templates.md
+++ b/docs/contribute/page-templates.md
@ -18,7 +18,7 @@ title: Using Page Templates

 <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.

-<h3 id="task_template">Task template</h3>
+<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
@ -36,10 +36,15 @@ variables, and then include templates/task.md:</p>
    <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 %}
@ -52,14 +57,14 @@ This page shows how to ...
 {% endcapture %}

 {% capture steps %}
-### Doing ...
+## Doing ...

 1. Do this.
 1. Do this next. Possibly read this [related explanation](...).
 {% endcapture %}

 {% capture discussion %}
-### Understanding ...
+## Understanding ...

 Here's an interesting thing to know about the steps you just did.
 {% endcapture %}
@ -77,7 +82,7 @@ Here's an interesting thing to know about the steps you just did.

 <p><a href="/docs/tasks/access-kubernetes-api/http-proxy-access-api">Using an HTTP Proxy to Access the Kubernetes API</a></p>

-<h3 id="tutorial_template">Tutorial template</h3>
+<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
@ -99,10 +104,14 @@ variables, and then include templates/tutorial.md:</p>
    <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 %}
@ -121,17 +130,17 @@ This page shows how to ...
 {% endcapture %}

 {% capture lessoncontent %}
-### Building ...
+## Building ...

 1. Do this.
 1. Do this next. Possibly read this [related explanation](...).

-### Running ...
+## Running ...

 1. Do this.
 1. Do this next.

-### Understanding the code
+## Understanding the code
 Here's something interesting about the code you ran in the preceding steps.
 {% endcapture %}

@ -153,7 +162,7 @@ Here's something interesting about the code you ran in the preceding steps.

 <p><a href="/docs/tutorials/stateless-application/run-stateless-application-deployment/">Running a Stateless Application Using a Deployment</a></p>

-<h3 id="concept_template">Concept template</h3>
+<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
@ -171,10 +180,14 @@ variables, and then include templates/concept.md:</p>
    <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 %}
@ -182,11 +195,11 @@ This page explains ...
 {% endcapture %}

 {% capture body %}
-### Understanding ...
+## Understanding ...

 Kubernetes provides ...

-### Using ...
+## Using ...

 To use ...
 {% endcapture %}
--- a/docs/contribute/review-issues.md
+++ b/docs/contribute/review-issues.md
@ -9,50 +9,50 @@ This page explains how you should review and prioritize documentation issues mad

 {% 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.  
+## 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.


-#### Actionable 
+### 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 
+* Allows contributors to have easy to find issues to work on


-#### Needs Tech Review 
+### 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 
+* Promotes transparency about level of work needed for the issue and that issue is in progress

-#### Needs Docs Review
+### 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


-### 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.   
+## 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
+### 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
+### 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 
+* Major content issues on a lower-trafficked page

-#### P3
+### P3
 * Typos and broken anchor links

-### Handling special issue types
+## Handling special issue types

-#### Duplicate issues
+### 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. 
+### 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 %}

--- a/docs/contribute/stage-documentation-changes.md
+++ b/docs/contribute/stage-documentation-changes.md
@ -14,7 +14,7 @@ Create a fork of the Kubernetes documentation repository as described in

 {% capture steps %}

-### Staging from your GitHub account
+## 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
@ -32,7 +32,7 @@ the master branch.

        https://<your-username>.github.io

-### Staging a pull request
+## Staging a pull request

 When you create a pull request, either against the master or &lt;vnext&gt;
 branch, your changes are staged in a custom subdomain on Netlify so that
@ -47,7 +47,7 @@ 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
+## 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
@ -66,7 +66,7 @@ web server:
 1. View your staged content at
 [http://localhost:4000](http://localhost:4000){: target="_blank"}.

-### Staging locally without Docker
+## Staging locally without Docker

 1. [Install Ruby 2.2 or later](https://www.ruby-lang.org){: target="_blank"}.

--- a/docs/contribute/style-guide.md
+++ b/docs/contribute/style-guide.md
@ -15,9 +15,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
@ -39,7 +39,7 @@ leads to an awkward construction.
  <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.
@ -50,7 +50,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>
@ -58,7 +58,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>
@ -66,7 +66,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>
@ -75,9 +75,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 (`).
@ -88,14 +88,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:

@ -117,11 +117,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>
@ -131,7 +131,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>
@ -141,7 +141,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."

@ -153,7 +153,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>
@ -161,9 +161,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.
@ -175,7 +175,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.

@ -185,13 +185,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.
--- a/docs/contribute/write-new-topic.md
+++ b/docs/contribute/write-new-topic.md
@ -13,7 +13,7 @@ Create a fork of the Kubernetes documentation repository as described in

 {% capture steps %}

-### Choosing a page type
+## 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:
@ -42,7 +42,7 @@ Each page type has a
 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
+## 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.
@ -54,18 +54,18 @@ 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
+## 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 
+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
+## Choosing a directory

 Depending on your page type, put your new file in a subdirectory of one of these:

@ -76,7 +76,7 @@ Depending on your page type, put your new file in a subdirectory of one of these
 You can put your file in an existing subdirectory, or you can create a new
 subdirectory.

-### Creating an entry in the table of contents
+## Creating an entry in the table of contents

 Depending page type, create an entry in one of these files:

@ -88,7 +88,7 @@ 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
+## 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
@ -107,7 +107,7 @@ Here's an example of using the `include` tag:

 <pre>&#123;% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %&#125;</pre>

-### Showing how to create an API object from a configuration file
+## 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
@ -127,7 +127,7 @@ Here's an example of a command that creates an API object from a configuration f
 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
+## Adding images to a topic

 Put image files in the `/images` directory. The preferred
 image format is SVG.