Update definitions for Task and Tutorial. #4206
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
k8s-ci-robot
added
the
cncf-cla: yes
steveperry-53
requested review from
chenopis,
jaredbhatti,
ryanmcginnis,
devin-donnelly and
cody-clark
chenopis
suggested changes
Jun 27, 2017
| @@ -22,17 +22,17 @@ is the best fit for your content: | |||
|
|
|||
| <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> | |||
| <td>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</>. 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></td> | |||
There was a problem hiding this comment.
The Configure a Pod to Use a Volume for Storage link is broken. I think it's because the closing tag should be </a>.
| </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> | ||
| <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. For an example of a concept topic, see <a href="docs/concepts/architecture/nodes/">Nodes</a>.</td> |
There was a problem hiding this comment.
This link is broken too. I think it's missing a leading / in the URL.
chenopis
suggested changes
Jun 27, 2017
| @@ -22,17 +22,17 @@ is the best fit for your content: | |||
|
|
|||
| <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> | |||
| <td>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></td> | |||
There was a problem hiding this comment.
Oops, one more. The Configure Liveness and Readiness Probes link is missing the opening quote before the URL.
chenopis
approved these changes
Jun 27, 2017
|
I agree. The examples really help differentiate the categories. |
chenopis
added a commit
that referenced
this pull request
Jun 27, 2017
…hub.io into release-1.6 * 'master' of https://github.com/kubernetes/kubernetes.github.io: Update definitions for Task and Tutorial. (#4206)
chenopis
added a commit
that referenced
this pull request
Jun 27, 2017
…hub.io into release-1.7 * 'master' of https://github.com/kubernetes/kubernetes.github.io: Update definitions for Task and Tutorial. (#4206)
|
/lgtm |
jesscodez
pushed a commit
that referenced
this pull request
Sep 22, 2017
* Update definitions for Task and Tutorial. * Fix broken links. * Still fixing broken links.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The purpose of this PR is to bring our definitions of Task, Tutorial, and Concept into alignment with recent discussions about what these page types mean.
Reviewers: Do you agree with me that a Task page should have steps that the reader can actually perform as he/she reads through the topic?
In the Tutorial definition, I haven't given an example of a Tutorial page, because our idea of what a tutorial should be is still evolving. I'm not sure whether any of the existing topics under Tutorials should serve as a canonical example of a tutorial.
This change is