From d80ab90cdb7cec7e5ff5d27273e9cb70f71799ba Mon Sep 17 00:00:00 2001 From: aimeeu Date: Wed, 25 Sep 2019 10:52:01 -0500 Subject: [PATCH] Add references to Content guide alongside Style guide (#16101) Add references to the Content guide where the Style guide was mentioned. Update the Contribute page (_index.md) Make Style and Content linkable everywhere Changed bullet list to numbered list in Content Guide to make referring to sections easier. Reverted change to bullet list - beyond scope of this PR Signed-off-by: Aimee Ukasick --- content/en/docs/contribute/_index.md | 4 +++- content/en/docs/contribute/advanced.md | 8 ++++---- content/en/docs/contribute/intermediate.md | 9 ++++----- content/en/docs/contribute/start.md | 13 ++++++++----- .../docs/contribute/style/content-organization.md | 5 +++-- content/en/docs/contribute/style/page-templates.md | 3 ++- 6 files changed, 24 insertions(+), 18 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 1c63c792a5a73..b903e4c8fc413 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -13,7 +13,9 @@ we're happy to have your help! Anyone can contribute, whether you're new to the project or you've been around a long time, and whether you self-identify as a developer, an end user, or someone who just can't stand seeing typos. -For information on the Kubernetes documentation style guide, see the [style guide](/docs/contribute/style/style-guide/). +For information on the Kubernetes documentation + content and style, see the + [Documentation style overview](/docs/contribute/style/style/). {{% capture body %}} diff --git a/content/en/docs/contribute/advanced.md b/content/en/docs/contribute/advanced.md index bb06be99bf814..dde34c0160df9 100644 --- a/content/en/docs/contribute/advanced.md +++ b/content/en/docs/contribute/advanced.md @@ -23,7 +23,7 @@ SIG Docs [approvers](/docs/contribute/participating/#approvers) take regular tur The PR wrangler’s duties include: -- Review [open pull requests](https://github.com/kubernetes/website/pulls) daily for quality and adherence to the [style guide](/docs/contribute/style/style-guide/). +- Review [open pull requests](https://github.com/kubernetes/website/pulls) daily for quality and adherence to the [Style](/docs/contribute/style/style-guide/) and [Content](/docs/contribute/style/content-guide/) guides. - Review the smallest PRs (`size/XS`) first, then iterate towards the largest (`size/XXL`). - Review as many PRs as you can. - Ensure that the CLA is signed by each contributor. @@ -78,11 +78,11 @@ An automated service, [`fejta-bot`](https://github.com/fejta-bot) automatically ## Propose improvements -SIG Docs -[members](/docs/contribute/participating/#members) can propose improvements. +SIG Docs [members](/docs/contribute/participating/#members) can propose improvements. After you've been contributing to the Kubernetes documentation for a while, you -may have ideas for improvement to the style guide, the toolchain used to build +may have ideas for improvement to the [Style Guide](/docs/contribute/style/style-guide/) +, the [Content Guide](/docs/contribute/style/content-guide/), the toolchain used to build the documentation, the website style, the processes for reviewing and merging pull requests, or other aspects of the documentation. For maximum transparency, these types of proposals need to be discussed in a SIG Docs meeting or on the diff --git a/content/en/docs/contribute/intermediate.md b/content/en/docs/contribute/intermediate.md index 086fb5350d95f..5ebb4fd933c6d 100644 --- a/content/en/docs/contribute/intermediate.md +++ b/content/en/docs/contribute/intermediate.md @@ -106,8 +106,7 @@ more information about the responsibilities of reviewers and approvers, see accuracy of the documentation modified or introduced in the PR.{{< /note >}} - An approver reviews pull request content for docs quality and adherence to - SIG Docs guidelines, such as the - [style guide](/docs/contribute/style/style-guide). Only people listed as + SIG Docs guidelines found in the Content and Style guides. Only people listed as approvers in the [`OWNERS`](https://github.com/kubernetes/website/blob/master/OWNERS) file can approve a PR. To approve a PR, leave an `/approve` comment on the PR. @@ -147,9 +146,8 @@ The ["Participating"](/docs/contribute/participating/#approvers) section contain the same browser window by default, so open it in a new window so you don't lose your partial review. Switch back to the **Files changed** tab to resume your review. - - Make sure the PR complies with the - [Documentation Style Guide](/docs/contribute/style/style-guide/) - and link the author to the relevant part of the style guide if not. + - Make sure the PR complies with the Content and Style guides; link the + author to the relevant part of the guide(s) if it doesn't. - If you have a question, comment, or other feedback about a given change, hover over a line and click the blue-and-white `+` symbol that appears. Type your comment and click **Start a review**. @@ -724,6 +722,7 @@ If you need to write a new topic, the following links are useful: - [Writing a New Topic](/docs/contribute/style/write-new-topic/) - [Using Page Templates](/docs/contribute/style/page-templates/) - [Documentation Style Guide](/docs/contribute/style/style-guide/) +- [Documentation Content Guide](/docs/contribute/style/content-guide/) ### SIG members documenting new features diff --git a/content/en/docs/contribute/start.md b/content/en/docs/contribute/start.md index dfcc9acaf9a2d..c710e8c795147 100644 --- a/content/en/docs/contribute/start.md +++ b/content/en/docs/contribute/start.md @@ -294,11 +294,14 @@ contribution guide. ## Review docs pull requests -People who are not yet approvers or reviewers can still review pull requests. -The reviews are not considered "binding", which means that your review alone -won't cause a pull request to be merged. However, it can still be helpful. Even -if you don't leave any review comments, you can get a sense of pull request -conventions and etiquette and get used to the workflow. +People who are not yet approvers or reviewers can still review pull requests. +The reviews are not considered "binding", which means that your review alone +won't cause a pull request to be merged. However, it can still be helpful. Even +if you don't leave any review comments, you can get a sense of pull request +conventions and etiquette and get used to the workflow. Take a look at the +[Content](/docs/contribute/style/content-guide/) and +[Style](/docs/contribute/style/style-guide/) guides before you review so you +get an idea of what the content should contain and how it should look. 1. Go to [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls). diff --git a/content/en/docs/contribute/style/content-organization.md b/content/en/docs/contribute/style/content-organization.md index a642ee83e8eed..55997dcaf5ab7 100644 --- a/content/en/docs/contribute/style/content-organization.md +++ b/content/en/docs/contribute/style/content-organization.md @@ -131,7 +131,8 @@ The [SASS](https://sass-lang.com/) source of the stylesheets for this site is st {{% capture whatsnext %}} -* [Custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) -* [Style guide](/docs/contribute/style/style-guide) +* Learn about [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) +* Learn about the [Style guide](/docs/contribute/style/style-guide) +* Learn about the [Content guide](/docs/contribute/style/content-guide) {{% /capture %}} diff --git a/content/en/docs/contribute/style/page-templates.md b/content/en/docs/contribute/style/page-templates.md index 033ddf6223eef..7521ee3ecba1f 100644 --- a/content/en/docs/contribute/style/page-templates.md +++ b/content/en/docs/contribute/style/page-templates.md @@ -215,7 +215,8 @@ An example of a published topic that uses the tutorial template is {{% capture whatsnext %}} -- Learn about the [style guide](/docs/contribute/style/style-guide/) +- Learn about the [Style guide](/docs/contribute/style/style-guide/) +- Learn about the [Content guide](/docs/contribute/style/content-guide/) - Learn about [content organization](/docs/contribute/style/content-organization/) {{% /capture %}}