From 77c7980a7485374442f85297c94fa756a9360461 Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Tue, 29 Nov 2016 12:21:55 -0500 Subject: [PATCH 1/5] New page for reviewing issues process adds a new page to the contribute section and navigation that describes the reviewing and labeling process for backlog/newly created issues --- _data/support.yml | 2 + docs/contribute/review-issues.md | 65 ++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 docs/contribute/review-issues.md diff --git a/_data/support.yml b/_data/support.yml index 1b8e80699a0..132a1013c30 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -14,6 +14,8 @@ toc: path: /docs/contribute/stage-documentation-changes/ - title: Using Page Templates path: /docs/contribute/page-templates/ + - title: Reviewing Documentation Issues + path: /docs/contribute/review-issues/ - title: Documentation Style Guide path: /docs/contribute/style-guide/ diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md new file mode 100644 index 00000000000..c74404a08e8 --- /dev/null +++ b/docs/contribute/review-issues.md @@ -0,0 +1,65 @@ +--- +--- + +{% capture overview %} + +This page explains how you should review and prioritize documentation issues made 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. + + +#### 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 + + +#### Tech Review Needed +* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a SME 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 + +#### Docs Review Needed +* 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. + +#### 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 + +### 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 %} From 18252f80e453265ab491ba1664dbdcadbece8b2f Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Tue, 29 Nov 2016 12:33:35 -0500 Subject: [PATCH 2/5] adding in duplicate seciton which was weirdly left out adding in left out section --- docs/contribute/review-issues.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md index c74404a08e8..58a72f66974 100644 --- a/docs/contribute/review-issues.md +++ b/docs/contribute/review-issues.md @@ -48,6 +48,7 @@ The following labels and definitions should be used to prioritize issues. If you ## 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. From 4ed6b4e6f462955ad07457cbe030eb372070650c Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Fri, 9 Dec 2016 14:15:28 -0500 Subject: [PATCH 3/5] Fixed whats next section in TOC and SME --- docs/contribute/review-issues.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md index 58a72f66974..51de6790642 100644 --- a/docs/contribute/review-issues.md +++ b/docs/contribute/review-issues.md @@ -8,7 +8,7 @@ This page explains how you should review and prioritize documentation issues mad {% capture body %} -## Categorizing issues +### 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. @@ -18,7 +18,7 @@ Issues should be sorted into different buckets of work using the following label #### Tech Review Needed -* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a SME needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant) +* 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 #### Docs Review Needed @@ -26,7 +26,7 @@ Issues should be sorted into different buckets of work using the following label * Topics can be brought to SIG meetings as agenda items -## Prioritizing Issues +### 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 @@ -45,12 +45,12 @@ The following labels and definitions should be used to prioritize issues. If you #### 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 +#### 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 %} From 59ede5a392cd9eb5964be341c9c29dc1eeaeec76 Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Wed, 4 Jan 2017 16:12:21 -0500 Subject: [PATCH 4/5] Correcting file name in support toc --- _data/support.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_data/support.yml b/_data/support.yml index eabd584e338..a79aa7addb3 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -10,7 +10,7 @@ toc: - docs/contribute/write-new-topic.md - docs/contribute/stage-documentation-changes.md - docs/contribute/page-templates.md - - docs/contribute/review-issues/ + - docs/contribute/review-issues.md - docs/contribute/style-guide.md From 267b1e25d2132a11db2888ba81e1187ccca89417 Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Wed, 4 Jan 2017 16:13:23 -0500 Subject: [PATCH 5/5] Adding page title --- docs/contribute/review-issues.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md index 51de6790642..476591e1daf 100644 --- a/docs/contribute/review-issues.md +++ b/docs/contribute/review-issues.md @@ -1,4 +1,5 @@ --- +title: Reviewing Documentation Issues --- {% capture overview %}