Restructure to reduce duplication

Signed-off-by: Celeste Horgan <celeste@cncf.io>
This commit is contained in:
Celeste Horgan
2020-04-02 16:03:51 -07:00
committed by bryan
parent fa63d85318
commit 8bde3f5cb4
20 changed files with 1274 additions and 1488 deletions
@@ -3,10 +3,6 @@ title: Documentation Content Guide
linktitle: Content guide
content_template: templates/concept
weight: 10
card:
name: contribute
weight: 20
title: Documentation Content Guide
---
{{% capture overview %}}
@@ -243,4 +243,4 @@ Renders to:
* 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/).
{{% /capture %}}
{{% /capture %}}
@@ -3,10 +3,6 @@ title: Documentation Style Guide
linktitle: Style guide
content_template: templates/concept
weight: 10
card:
name: contribute
weight: 20
title: Documentation Style Guide
---
{{% capture overview %}}
@@ -15,10 +11,12 @@ 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
documentation, read the [Documentation Content
Guide](/docs/contribute/style/content-guide/) and follow the instructions on
[using page templates](/docs/contribute/style/page-templates/) and [creating a
documentation pull request](/docs/contribute/start/#improve-existing-content).
documentation, read the [Documentation Content Guide](/docs/contribute/style/content-guide/) and follow the instructions on
[using page templates](/docs/contribute/style/page-templates/) and [creating a documentation pull request](/docs/contribute/new-content/open-a-pr).
Changes to the style guide are made by SIG Docs as a group. To propose a change
or addition, [add it to the agenda](https://docs.google.com/document/d/1ddHwLK3kUMX1wVFIwlksjTk0MsqitBnWPe1LRa1Rx5A/edit) for an upcoming SIG Docs meeting, and attend the meeting to participate in the
discussion.
{{% /capture %}}
@@ -10,7 +10,7 @@ This page shows how to create a new topic for the Kubernetes docs.
{{% capture prerequisites %}}
Create a fork of the Kubernetes documentation repository as described in
[Start contributing](/docs/contribute/start/).
[Open a PR](/docs/new-content/open-a-pr/).
{{% /capture %}}
{{% capture steps %}}
@@ -24,8 +24,8 @@ Type | Description
:--- | :----------
Concept | 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 while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.
Task | A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a>
Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
{{< /table >}}
Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
{{< /table >}}
Use a template for each new page. Each page type has a
[template](/docs/contribute/style/page-templates/)
@@ -162,7 +162,6 @@ image format is SVG.
{{% /capture %}}
{{% capture whatsnext %}}
* 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/).
* Learn about [using page templates](/docs/contribute/page-templates/).
* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).
{{% /capture %}}