Merge pull request #723 from pwittrock/templatedd

More udpates to how to use templates.

docs/templatedemos/index.md

@@ -10,129 +10,121 @@ $(function() {
 
 Check out the kubernetes/kubernetes.github.io repo and the docsv2 branch.
 
-## Step 1: Fork and Clone the repo
+### Step 1: Fork and Clone the repo
 - Fork [kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io)
 - [Setup your GitHub authentication using ssh](https://help.github.com/articles/generating-an-ssh-key/)
-- Clone the repo under go/src/k8s.io
+- Clone the repo under ~/go/src/k8s.io
 
-```sh
+```shell
 cd ~/go/src/k8s.io
 git clone git@github.com:<you-github-repo>/kubernetes.github.io
 cd kubernetes.github.io
 git remote add upstream https://github.com/kubernetes/kubernetes.github.io.git
 ```
 
-## Step 2: Move to the docsv2 branch
+### Step 2: Switch to the docsv2 branch
-
+Docs v2 development is being performed in the `docsv2` branch.  This is the branch
-Docs v2 development is being performed in the docsv2 branch.  This is the branch
 you want to be working from.
 
-From ~/go/src/k8s.io/kubernetes.github.io
+From ~/go/src/k8s.io/kubernetes.github.io:
 
 ```shell
-git checkout -b docsv2 # switch to the docsv2 branch
+git checkout -b docsv2
-git fetch upstream # get the latest upstream changes
+git fetch upstream
-git reset --hard upstream/docsv2 # sync the branch to upstream
+git reset --hard upstream/docsv2
 ```
 
-## Step 3: Make sure you can serve rendered docs locally from your dev box
+### Step 3: Make sure you can serve rendered docs locally from your dev box
 
 - [Follow the editdocs instructions](http://kubernetes.io/editdocs/)
 
 # Writing Docs Using Templates
 
-<div id="accordion">
+## Types of Templates
-<h3>Concept Overviews</h3>
+- Concept Template
+  - Introduce K8s Api Objects e.g. Pod
+- Task Template
+  - Step-by-step guide for "Doing X".  
+  - Useful for breaking down various ways of configuring Concepts into sub-topics
+- Landing Pages Template
+  - Collection of click-able cards on a grid
+  - Useful for directing users to actual content from a visual Table of Contents
+
+# Concept Overview Template Details
 <div>{% capture instructions %}
 
 A concept overview covers the most essential, important information about core
 Kubernetes concepts and features.  Examples of Concepts include `Pod`,
 `Deployment`, `Service`, etc.
 
-### Example
+## Reference Examples
 
-- [Source Link](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)
+- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)
-- [Rendered Link](filledout/)
+- [Link to Rendered Template](filledout/)
 
-### Usage
+## Usage
 
-To create a new concept overview page, create a new file under
+### Creating the file
-`docs/your-concept-name/index.md`.
 
-The file should start with the set of tags to apply to the concept and end
+To create a new concept overview page, create a new directory with the concept
-with an `include templates/concept-overview.md` block.
+name under the docs directory and an index.md file.
+e.g. `docs/your-concept-name/index.md`.
 
-The file needs to have the following `capture` sections:
+### Adding the Template sections
 
-- concept
+- tags
-- when_to_use
-- when_not_to_use
-- status
-- usage
 
 ```liquid{% raw %}
 ---
-add
+include
 tags
-here
-e.g.
-pod
 ---
-{% capture concept %}
+```
-Name of the Concept goes here (e.g. Pod)
-{% endcapture %}
 
-{% capture what_is %}
+- concept: the concept name e.g. Pod
-1 sentence description of the Concept that describes the function it performs.
-If needed:
-- add
-- clarifying
-- bullet points
 
-![Also add a diagram](/images/docs/file.svg){: style="max-width: 25%" }
+``` #
+{% capture concept %}{% endcapture %}
+```
 
-{% comment %}
+- what_is: one sentence description the function / role  of the concept.  Diagrams are helpful.
-Include a comment indicating where an editable image exists:
-https://drive.google.com/open?id=1pQe4-s76fqyrzB8f3xoJo4MPLNVoBlsE1tT9MyLNINg
-{% endcomment %}
-{% endcapture %}
 
-{% capture when_to_use %}
+``` #
-Clarify precisely when and how to use this Concept.  Disambiguate when to use
+{% capture what_is %}{% endcapture %}
-this instead of similar concepts.  e.g. Secret vs ConfigMap,
+```
-Deployment vs Job vs other controllers, Service vs Ingress.
 
-| Tables | Can Be |
+- when_to_use: disambiguate when to use this vs alternatives
-|------------|----------------|
-| Helpful | When |
-| Comparing | Functionality |
-| Across | Concepts |
-{% endcapture %}
 
-{% capture when_not_to_use %}
+``` #
-Call out common anti-patterns to be avoided.
+{% capture when_to_use %}{% endcapture %}
-{% endcapture %}
+```
 
-{% capture status %}
+- when_not_to_use: highlight common anti-patterns
-Describe how to get the current status of an instance in a cluster using kubectl
 
-Use a table to clarify the response.
+``` #
+{% capture when_not_to_use %}{% endcapture %}
+```
 
-Consider status from kubectl describe as well.
+- status: how to get the status for this object using kubectl
-{% endcapture %}
 
-{% capture usage %}
+``` #
-If the concept interacts with or is embedded in other Concepts, clarify that here.
+{% capture status %}{% endcapture %}
-For Services this should call out the meaning of the label selectors, for Volumes
+```
-this should call out that they are defined within a Pod.
 
-Include the example yaml here
+- usage: example yaml
-{% endcapture %}
 
+``` #
+{% capture usage %}{% endcapture %}
+
+```
+
+- template: include the template at the end
+
+``` #
 {% include templates/concept-overview.md %}
 {% endraw %}```
 
-### Adding page to navigation
+### Adding the page to navigation
 
 Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `concepts.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page.
 
@@ -141,46 +133,74 @@ Once your page is saved, somewhere in the `/docs/` directory, add a reference to
 
 </div>
 
-
+# Task Template Details
-<h3>Task</h3>
 <div>{% capture instructions %}
 
 A task page offers step-by-step instructions for completing a task with Kubernetes. **A task page should be narrowly focused on task completion and not delve into concepts or reference information.**
 
-### Demos
+## Example
-
+- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/task.md)
-- [Blank](blanktask/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blanktask.md))
+- [Link to Rendered Page](task/)
-- [Filled Out](task/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/task.md))
 
 ### Usage
 
+## Creating the file
+
+To create a new task page, create a file under docs/tasks/task-name.
+e.g. `docs/tasks/your-task-name`.
+
+### Adding the Template sections
+
+- tags
+
 ```liquid{% raw %}
 ---
+tags
 ---
+```
+
+- purpose: one sentence description of the task and motivation
+
+``` #
 {% capture purpose %}{% endcapture %}
+```
+
+- recommended_background: List of Concepts referenced or other Tasks, Tutorials that provide needed context
+
+``` #
 {% capture recommended_background %}{% endcapture %}
+```
+
+- set_by_step: Add multiple sections.  1 per step in the task.
+
+``` #
 {% capture step_by_step %}{% endcapture %}
+```
+
+- template: include the template at the end
+
+``` #
 {% include templates/task.md %}
 {% endraw %}```
 
-### Adding page to navigation
+### Adding the page to navigation
 
-Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `tasks.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page.
+Add a reference to the `tasks.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page.
 
 {% endcapture %}
 {{ instructions | markdownify }}
 
 </div>
 
-<h3>Landing Pages</h3>
+# Landing Pages
 <div>{% capture instructions %}
 
 Landing pages are a set of clickable "cards" arranged in a grid. Each card has a heading and description, and optioninall, a thumbnail image. They are meant to be index pages that quickly forward users on to deeper content.
 
 ### Demos
 
-- [Blank](blanklanding/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blanklanding.md))
+- [Link to Example Landing Page](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/landingpage.md)
-- [Filled Out](landingpage/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/landingpage.md))
+- [Link to Rendered Landing Page](landingpage/)
 
 ### Usage
 
@@ -209,14 +229,14 @@ Once your page is saved, somewhere in the `/docs/` directory, add a reference to
 </div>
 
 
-<h3>kubectl yaml</h3>
+# kubectl yaml
 <div>{% capture instructions %}
 You probably shouldn't be using this, but we also have templates which consume YAML files that are generated by the Kubernetes authors. These are turned into pages which display the reference information for the various CLI tools.
 
 ### Demos
 
-- [Blank](blankkubectl/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blankkubectl.md))
+- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/kubectl.md)
-- [Filled Out](kubectl/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/kubectl.md))
+- [Link to Rendered Template](kubectl/)
 
 ### Adding page to navigation