From fc894c9eb6b2d9b47e0b9029bcc27c3db5a053af Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 13 Apr 2020 13:17:15 -0700 Subject: [PATCH 1/4] Update contributing docs and move back from https://github.com/knative/community --- CONTRIBUTING.md | 412 +++++++++++++++++++++++++++++++++++++++++++ README.md | 24 +++ new-page-template.md | 88 +++++++++ 3 files changed, 524 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 new-page-template.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..0856ade990f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,412 @@ +# Contributing to knative/docs + +- [Before you begin](#before-you-begin) +- [Contributing to the documentation](#contributing-to-the-documentation) +- [Docs contributor roles](#docs-contributor-roles) + +**First off, thanks for taking the time to contribute!** + +The following are guidelines for contributing to the Knative documentation. +These are just guidelines, not rules. Use your best judgment, and feel free to +propose changes to this document in a pull request. + +## Before you begin + +### Code of conduct + +Knative follows the [Knative Code of Conduct](../CODE-OF-CONDUCT.md). By +participating, you are expected to uphold this code. Please report unacceptable +behavior to knative-code-of-conduct@googlegroups.com. + +### Contributor license agreements + +We'd love to accept your contributions! But before we can take them, you need to +fill out the [Google CLA](https://cla.developers.google.com). Important: You +must fill out the CLA with the same email address that you used to create your +GitHub account. + +Once you are CLA'ed, we'll be able to accept your pull requests. This is +necessary because you own the copyright to your changes, even after your +contribution becomes part of this project. So this agreement simply gives us +permission to use and redistribute your contributions as part of the project. + +Note: Your contributions are verified using the email address for which you +use to sign the CLA. Therefore, +[setting your GitHub account to private](https://help.github.com/en/articles/setting-your-commit-email-address) +is unsupported because all commits from private accounts are sent from the `noreply` +email address. + +### Style guide + +Knative documentation follows the +[Google Developer Documentation Style Guide](https://developers.google.com/style/); +use it as a reference for writing style questions. + +## Contributing to the documentation + +### Reporting documentation issues + +Knative uses Github issues to track documentation issues and requests. If you +see a problem with the documentation, submit an issue using the following steps: + +1. Check the [Knative docs issues list](https://github.com/knative/docs/issues) + before creating an issue to avoid making a duplicate. +2. Use the [correct template](https://github.com/knative/docs/issues/new) for + your new issue. There are two templates available: + - **Bug report**: If you're reporting an error in the existing documentation, + use this template. This could be anything from broken samples to typos. + When you create a bug report, include as many details as possible and + include suggested fixes to the issue. If you know which Knative component + your bug is related to, you can assign the appropriate + [Working Group Lead](../WORKING-GROUPS.md). + - **Feature request**: For upcoming changes to the documentation or requests + for more information on a particular subject. + +Note that code issues should be filed against the +[individual Knative repositories](http://github.com/knative), while +documentation issues should go in the +[`knative/docs`repo](https://github.com/knative/docs/issues). If the issue is +specific to the [https://knative.dev](https://knative.dev) website, open the +issue in the [`knative/website`repo](https://github.com/knative/website/issues). + +### Working group + +The [Knative Documentation Working Group](../WORKING-GROUPS.md#documentation) +meets weekly on Tuesdays and alternates between a 9am PT and a 4:30pm PT time to +accommodate contributors in both the EMEA and APAC timezones. +[Click here](https://calendar.google.com/calendar/embed?src=google.com_18un4fuh6rokqf8hmfftm5oqq4%40group.calendar.google.com) +to see the exact dates on the Knative working group calendar. If you're +interested in becoming more involved in Knative's documentation, start attending +the working group meetings. You'll meet the writers currently steering our +documentation efforts, who are happy to help you get started. + +### Getting started + +There are a couple different ways to jump in to the Knative doc set: + +- Look for a + [Good First Issue](https://github.com/knative/docs/labels/kind%2Fgood-first-issue) + in the backlog. + +- Try out Knative and send us feedback. For example, run through one of the + [install guides](https://github.com/knative/docs/tree/master/docs/install/README.md) and then try + [Getting Started with Knative Serving](https://github.com/knative/docs/tree/master/docs/install/getting-started-knative-app.md). + + You should keep a + [friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging) + of your experience and then use that to open your first set of PRs. Examples: + + - What was hard for you? + - Did you stumble on something because it wasn't clear? + - Was a dependency not mentioned? + +**A few pointers and other considerations** + +- Think about how you can improve the documentation as a whole.
For + example, how can you fix the issue you found so that others don't run into the + same challenges? + +- Are there multiple places that could be fixed? + + - Are there other pages that you should apply your update? + + - Would it help if there was a link to more or related information on a the + page? On a related page? + +- Was the title or description misleading? Did you expect to find something + else? + +- If you find something and don't have the bandwidth to open a PR, make us aware + of the pain point and open an + [Issue](https://github.com/knative/docs/issues/new). + +### Submitting documentation PRs - what to expect + +Here's what generally happens when you open a PR against the `knative/docs` +repo: + +1. One of the assigned repo maintainers will triage the PR by assigning relative + priority, adding appropriate labels, and performing an initial documentation + review. +1. If the PR involves significant technical changes, for example new features, + or new and changed sample code, the PR is assigned to a Subject Matter Expert + (SME), typically an engineer working on Knative, for technical review and + approval. +1. When both the technical writers and SMEs are satisfied with the quality of + the writing and the technical accuracy of the content, the PR can be merged. + A PR requires two labels before it can merge: `lgtm` and `approved`. + + - The SME is responsible for reviewing the technical accuracy and adding the + `lgtm` label. + + - The + [Knative technical writers](https://github.com/knative/docs/blob/master/OWNERS_ALIASES) + are who provide the `approved` label when the content meets quality, + clarity, and organization standards (see [Style Guide](#style-guide)). + +We appreciate contributions to the docs, so if you open a PR we will help you +get it merged. You can also post in the `#docs` +[Slack channel](https://knative.slack.com/) to get input on your ideas before +creating a PR. + +### Putting your docs in the right place + +There are currently two general types of Knative docs, either contributor +related content, or external-facing user content. + +#### Choosing the correct repo + +Depending on the type of content that you want to contribute, it might belong in +one of the Knative code repositories (`knative/serving`, `knative/eventing`, +etc.) or in `knative/docs`, the Knative documentation repo. + +- **Contributor-focused content** + + - _Documentation_: Includes content that is component specific and relevant + only to contributors of a given component. Contributor focused documentation + is located in the corresponding `docs` folder of that component's + repository. For example, if you contribute code to the Knative Serving + component, you might need to add contributor focused information into the + `docs` folder of the + [knative/serving repo](https://github.com/knative/serving/tree/master/docs/). + + - _Code samples_: Includes contributor related code or samples. Code or + samples that are contributor focused also belong in their corresponding + component's repo. For example, Eventing specific test code is located in the + [knative/eventing tests](https://github.com/knative/eventing/tree/master/test) + folder. + +- **User-focused content** + + - _Documentation_: Includes all content for Knative users. The external-facing + user documentation belongs in the + [`knative/docs` repo](https://github.com/knative/docs). All content in + `knative/docs` is published to [https://knative.dev](https://knative.dev). + + - _Code samples_: Includes user-facing code samples and their accompanying + step-by-step instructions. User code samples are currently separated into + two different locations within the `knative/docs` repo. See the following + section for details about determining where you can add your code sample. + +##### Determining where to add user focused code samples + +There are currently two categories of user-focused code samples, _Knative owned +and maintained_ and _Community owned and maintained_. + +- **Knative owned and maintained**: Includes code samples that are actively + maintained and e2e tested. To ensure content currency and balance available + resource, only the code samples that meet the following requirements are + located in the `docs/[*component*]/samples` folders of the `knative/docs` + repo: + + - _Actively maintained_ - The code sample has an active Knative team member + who has committed to regular maintenance of that content and ensures that + the code is updated and working for every product release. + - _Receives regular traffic_ - To avoid hosting and maintaining unused or + stale content, if code samples are not being viewed and fail to receive + attention or use, those samples will be moved into the + "[community maintained](https://github.com/knative/docs/tree/master/community/samples)" + set of samples. + - _Passes e2e testing_ - All code samples within `docs/[*component*]/samples` + folders must align with (and pass) the + [`e2e` tests](https://github.com/knative/docs/tree/master/test). + + Depending on the Knative component covered by the code sample that you want to + contribute, your PR should add that sample in one of the following folders: + + - Eventing samples: + [`/docs/eventing/samples`](https://github.com/knative/docs/tree/master/docs/eventing/samples) + - Serving samples: + [`/docs/serving/samples`](https://github.com/knative/docs/tree/master/docs/serving/samples) + +- **Community owned and maintained samples**: Code samples that have been + contributed by Knative community members. These samples might not receive + regular maintenance. It is possible that a sample is no longer current and is + not actively maintained by its original author. While we encourage a + contributor to maintain their content, we acknowledge that it's not always + possible for certain reasons, for example other commitments and time + constraints. + +While a sample might be out of date, it could still provide assistance and help +you get up-and-running with certain use-cases. If you find that something is not +right or contains outdated info, open an +[Issue](https://github.com/knative/docs/issues/new). The sample might be fixed +if bandwidth or available resource exists, or the sample might be taken down and +archived into the last release branch where it worked. + +#### Choosing the correct branch + +It is likely that your docs contribution is either for new or changed features +in the product, or for a fix or update existing content. + +- **New or changed features**: If you are adding or updating documentation for a + new or changed feature, you likely want to open your PR against the `master` + branch. All pre-release content for active Knative development belongs in + [`master`](https://github.com/knative/docs/tree/master/). + +- **Fixes and updates**: If you find an issue in a past release, for example a + typo or out-of-date content, you likely need to open multiple and subsequent + PRs. If not a followup PR, at least add the "`cherrypick` labels" to your + original PR to indicate in which of the past release that your change affects. + + For example, if you find a typo in a page of the `v0.5` release, then that + page in the `master` branch likely also has that typo. + + To fix the typo: + + 1. Open a PR against the + [`master`](https://github.com/knative/docs/tree/master/) branch. + 1. Add one or more `cherrypick-#.#` labels to that PR to indicate which of + the past release branches should also be fixed. Generally, we only + maintain the most recent numbered release. + 1. If you want to complete the fix yourself (**best practice**), you then open a + subsequent PR by running `git cherry-pick [COMMIT#]` against the + `release-0.5`. + Where `[COMMIT#]` is the commit of the PR that you merged in `master`. + + Note: Depending on workload and available bandwidth, one of the Knative + team members might be able to help handle the `git cherry-pick` in order + to push the fix into the affected release branch(es). + +See a list of the available documentaion versions in the +[branches page](https://github.com/knative/docs/branches) +of the `knative/docs` repo. + +## Assigning owners and reviewers + +For both documentation and code samples, you should assign your PR to a single +owner ("_Assignee_"). It's best to set the "Assignee" and include other +stakeholders as "Reviewers" rather than leaving it unassigned or allowing +[Prow](https://prow.k8s.io/command-help) to auto assign reviewers. + +Use the `/assign` command to set the owner. For example: `/assign @owner_id` + +For code samples, initially set the owner of your PR to the SME who should +review for technical accuracy. If you don't know who the appropriate owner is, +nor who your reviewers should be for your PR, you can assign the +[current working group lead](../WORKING-GROUPS.md) of the related component. + +If you want to notify and include other stakeholders in your PR review, use the +`/cc` command. For example: `/cc @stakeholder_id1 @stakeholder_id2` + +## Docs contributor roles + +Because contributing to the documentation requires a different skill set than +contributing to the Knative code base, we've defined the roles of documentation +contributors separately from the roles of code contributors. + +If you're looking for code contributor roles, see [ROLES](../ROLES.md). + +### Member + +Established contributor to the Knative docs. + +Members are continuously active contributors in the community. They can have +issues and PRs assigned to them, might participate in working group meetings, +and pre-submit tests are automatically run for their PRs. Members are expected +to remain active contributors to the Knative documentation. + +All members are encouraged to help with PR reviews, although each PR must be +reviewed by an official [Approver](#approver). In their review, members should +be looking for technical correctness of the documentation, adherence to the +[style guide](https://developers.google.com/style/), good spelling and grammar +(writing quality), intuitive organization, and strong documentation usability. +Members should be proficient in at least one of these review areas. + +### Requirements + +- Has made multiple contributions to the project or community. Contributions + might include, but are not limited to: + + - Authoring and reviewing PRs on GitHub in the Docs or Website repos. + + - Filing and commenting on issues on GitHub. + + - Contributing to working group or community discussions. + +- Subscribed to + [knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev). + +- Actively contributing to 1 or more areas. + +- Sponsored by 1 approver. + + - Done by adding GitHub user to Knative organization. + +### Responsibilities and privileges + +- Responsive to issues and PRs assigned to them. + +- Active owner of documents they have contributed (unless ownership is + explicitly transferred). + + - Addresses bugs or issues in their documentation in a timely manner. + +### Becoming a member + +First, reach out to an approver and ask them to sponsor you so that you can +become a member. The easiest way to do this is using Slack. + +If they are supportive of your membership, your sponsor will reach out to the +Knative Steering committee to ask that you be added as a member of the Knative +org. + +Once your sponsor notifies you that you've been added to the Knative org, open a +PR to add yourself as a docs-reviewer in the +[OWNERS_ALIASES](https://github.com/knative/docs/tree/master/OWNERS_ALIASES) +file. + +## Approver + +Docs approvers are able to both review and approve documentation contributions. +While documentation review is focused on writing quality and correctness, +approval is focused on holistic acceptance of a contribution including: +long-term maintainability, adhering to style guide conventions, overall +information architecture, and usability from an engineering standpoint. Docs +approvers will enlist help from engineers for reviewing code-heavy contributions +to the Docs repo. + +### Requirements + +- Reviewer of the Docs repo for at least 3 months. + + - Proficient in reviewing all aspects of writing quality, including grammar + and spelling, adherence to style guide conventions, organization, and + usability. Can coach newer writers to improve their contributions in these + areas. + +- Primary reviewer for at least 10 substantial PRs to the docs, showing + substantial ability to coach for writing development. + +- Reviewed or merged at least 30 PRs to the docs. + +- Nominated by an area lead (with no objections from other leads). + + - Done through PR to update an OWNERS file. + +### Responsibilities and privileges + +- Responsible for documentation quality control via PR reviews. + + - Focus on long-term maintainability, adhering to style guide conventions, + overall information architecture, and usability from an engineering + standpoint. + +- Expected to be responsive to review requests as per + [community expectations](REVIEWING.md). + +- Mentor members and contributors to improve their writing. + +- Might approve documentation contributions for acceptance, but will ask for + engineering review for code-heavy contributions. + +### Becoming an approver + +If you want to become an approver, make your goal clear to the current Knative +Docs approvers, either by contacting them in Slack or announcing your intention +to become an approver at a meeting of the Documentation Working Group. + +Once you feel you meet the criteria, you can ask one of the current approvers to +nominate you to become an approver. If all existing approvers agree that you +meet the criteria open a PR to add yourself as a docs-approver in the +[OWNERS_ALIASES](https://github.com/knative/docs/tree/master/OWNERS_ALIASES) file. diff --git a/README.md b/README.md index a1939b27f29..001d114bd1f 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,30 @@ Each release of the Knative docs are available in the website (starting with 0.3) and their source files are all stored in [branches of this repo](./doc-releases.md). +## Contributing + +We're excited that you're interested in contributing to the Knative documentation! Check out the resources below to get started. + +## Getting started + +- [How to contribute](./CONTRIBUTING.md) -- Contains information about how + to contribute and outlines the roles for Docs contributors. + +- [Template + page](https://raw.githubusercontent.com/knative/docs/master/new-page-template.md) + -- A blank documentation page that demonstrates how to format a new page and + includes tips on structuring your documentation. + +## Getting help + +- [#docs on the Knative Slack](https://slack.knative.dev) -- The #docs channel + is the best place to go if you have questions about making changes to the + documentation. We're happy to help! + +- [Documentation working group](../WORKING-GROUPS.md#documentation) -- Come join + us in the working group to meet other docs contributors and ask any questions + you might have. + ## Help and support Your help and feedback is always welcome! diff --git a/new-page-template.md b/new-page-template.md new file mode 100644 index 00000000000..a2ea355f909 --- /dev/null +++ b/new-page-template.md @@ -0,0 +1,88 @@ +# Documentation Template + +This page is intended to provide best-practices for starting a new document. + +## Frontmatter + +[Hugo](https://gohugo.io/) uses a set of metadata at the beginning of +the page called +[frontmatter](https://gohugo.io/content-management/front-matter/) to +indicate information like the page title and link rendering in the +sidebar. + +Frontmatter needs to be formatted like this: +```yaml +--- +# This section is called the "frontmatter" for your page +title: "Title for your page" # Use sentence case for titles +linkTitle: "Template: New docs page" +# The linkTitle field (above) is optional; use it to provide a shorter link if your page title is very long +weight: 50 # This affects the placement of the link in the sidebar on the left. Pages are ordered from top to bottom by weight, lowest to highest. +type: "docs" # You won't need to update this. +#aliases: +# - /docs/example/redirect/moved-renamed-page +# - /docs/another-example +# Has the page ever moved? If yes, include the prior location above, starting with path from the site root (for example /docs/, /blog/, or /community/). The old URL will redirect to this new file. For a new pages, "aliases" are not required. +--- +``` + +This guide shows you how to do something very cool. Make sure to include +a value proposition for the user: for example, this guide shows you how to do X, +which is useful for doing Y and Z. Make sure you answer the questions "what does +this guide show you how to do?" and "why would someone want to do this?". + +## Before you begin + +You need: + +- A Kubernetes cluster with [Knative installed](../install/README.md). +- Anything else? + +## Break steps into logical sections + +Avoid nesting headings directly on top of each other with no text inbetween. + +1. Use ordered lists for steps. + +1. Step number two. + +1. Step number three. + + + +### You can use smaller sections within sections for related tasks + +Avoid nesting headings directly on top of each other with no text inbetween. + +Put code into a code block. + +1. Here's a code snippet: + + ```bash + kubectl apply --filename test.yaml + ``` +1. Another code snippet: + + ```bash + kubectl apply --filename test2.yaml + ``` + +Always explain code snippets thoroughly so that how they work or what they do +is clear. + +## Cleaning up + +If your guide installs a sample application, show the user how to delete it. + +## What's next + +Provide links to other relevant topics, if applicable. Once someone has +completed these steps, what might they want to do next? + +- [Link](./page.md) +- [Link](./page.md) +- [Link](./page.md) From a7c7c250267046197bcc408f2ee197634532fa55 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 13 Apr 2020 13:30:11 -0700 Subject: [PATCH 2/4] Fix misspellings and trailing whitespace --- CONTRIBUTING.md | 6 +++--- new-page-template.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0856ade990f..f9d10825218 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,9 +31,9 @@ contribution becomes part of this project. So this agreement simply gives us permission to use and redistribute your contributions as part of the project. Note: Your contributions are verified using the email address for which you -use to sign the CLA. Therefore, +use to sign the CLA. Therefore, [setting your GitHub account to private](https://help.github.com/en/articles/setting-your-commit-email-address) -is unsupported because all commits from private accounts are sent from the `noreply` +is unsupported because all commits from private accounts are sent from the `noreply` email address. ### Style guide @@ -268,7 +268,7 @@ in the product, or for a fix or update existing content. team members might be able to help handle the `git cherry-pick` in order to push the fix into the affected release branch(es). -See a list of the available documentaion versions in the +See a list of the available documentation versions in the [branches page](https://github.com/knative/docs/branches) of the `knative/docs` repo. diff --git a/new-page-template.md b/new-page-template.md index a2ea355f909..bc3f3c3a15e 100644 --- a/new-page-template.md +++ b/new-page-template.md @@ -41,7 +41,7 @@ depending on where the new page is located in the file structure. --> ## Break steps into logical sections -Avoid nesting headings directly on top of each other with no text inbetween. +Avoid nesting headings directly on top of each other with no text in between. 1. Use ordered lists for steps. @@ -56,7 +56,7 @@ Avoid nesting headings directly on top of each other with no text inbetween. ### You can use smaller sections within sections for related tasks -Avoid nesting headings directly on top of each other with no text inbetween. +Avoid nesting headings directly on top of each other with no text in between. Put code into a code block. From 8325698a5f3f2d006e90a811c44a87d3bfd0d6f8 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 13 Apr 2020 13:38:41 -0700 Subject: [PATCH 3/4] Fix broken links --- CONTRIBUTING.md | 16 ++++++++-------- README.md | 9 ++++----- new-page-template.md | 8 ++++---- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9d10825218..029cbe90c5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ propose changes to this document in a pull request. ### Code of conduct -Knative follows the [Knative Code of Conduct](../CODE-OF-CONDUCT.md). By +Knative follows the [Knative Code of Conduct](https://github.com/knative/community/blob/master/CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to knative-code-of-conduct@googlegroups.com. @@ -58,7 +58,7 @@ see a problem with the documentation, submit an issue using the following steps: When you create a bug report, include as many details as possible and include suggested fixes to the issue. If you know which Knative component your bug is related to, you can assign the appropriate - [Working Group Lead](../WORKING-GROUPS.md). + [Working Group Lead](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md). - **Feature request**: For upcoming changes to the documentation or requests for more information on a particular subject. @@ -71,7 +71,7 @@ issue in the [`knative/website`repo](https://github.com/knative/website/issues). ### Working group -The [Knative Documentation Working Group](../WORKING-GROUPS.md#documentation) +The [Knative Documentation Working Group](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md#documentation) meets weekly on Tuesdays and alternates between a 9am PT and a 4:30pm PT time to accommodate contributors in both the EMEA and APAC timezones. [Click here](https://calendar.google.com/calendar/embed?src=google.com_18un4fuh6rokqf8hmfftm5oqq4%40group.calendar.google.com) @@ -89,8 +89,8 @@ There are a couple different ways to jump in to the Knative doc set: in the backlog. - Try out Knative and send us feedback. For example, run through one of the - [install guides](https://github.com/knative/docs/tree/master/docs/install/README.md) and then try - [Getting Started with Knative Serving](https://github.com/knative/docs/tree/master/docs/install/getting-started-knative-app.md). + [install guides](docs/install/README.md) and then try + [Getting Started with Knative Serving](docs/serving/getting-started-knative-app.md). You should keep a [friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging) @@ -284,7 +284,7 @@ Use the `/assign` command to set the owner. For example: `/assign @owner_id` For code samples, initially set the owner of your PR to the SME who should review for technical accuracy. If you don't know who the appropriate owner is, nor who your reviewers should be for your PR, you can assign the -[current working group lead](../WORKING-GROUPS.md) of the related component. +[current working group lead](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md) of the related component. If you want to notify and include other stakeholders in your PR review, use the `/cc` command. For example: `/cc @stakeholder_id1 @stakeholder_id2` @@ -295,7 +295,7 @@ Because contributing to the documentation requires a different skill set than contributing to the Knative code base, we've defined the roles of documentation contributors separately from the roles of code contributors. -If you're looking for code contributor roles, see [ROLES](../ROLES.md). +If you're looking for code contributor roles, see [ROLES](https://github.com/knative/community/blob/master/ROLES.md). ### Member @@ -393,7 +393,7 @@ to the Docs repo. standpoint. - Expected to be responsive to review requests as per - [community expectations](REVIEWING.md). + [community expectations](https://github.com/knative/community/blob/master/REVIEWING.md). - Mentor members and contributors to improve their writing. diff --git a/README.md b/README.md index 001d114bd1f..1cd88fed655 100644 --- a/README.md +++ b/README.md @@ -48,10 +48,9 @@ We're excited that you're interested in contributing to the Knative documentatio - [How to contribute](./CONTRIBUTING.md) -- Contains information about how to contribute and outlines the roles for Docs contributors. -- [Template - page](https://raw.githubusercontent.com/knative/docs/master/new-page-template.md) - -- A blank documentation page that demonstrates how to format a new page and - includes tips on structuring your documentation. +- [Template page](./new-page-template.md) -- A blank documentation page that + demonstrates how to format a new page and includes tips on structuring your + documentation. ## Getting help @@ -59,7 +58,7 @@ We're excited that you're interested in contributing to the Knative documentatio is the best place to go if you have questions about making changes to the documentation. We're happy to help! -- [Documentation working group](../WORKING-GROUPS.md#documentation) -- Come join +- [Documentation working group](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md#documentation) -- Come join us in the working group to meet other docs contributors and ask any questions you might have. diff --git a/new-page-template.md b/new-page-template.md index bc3f3c3a15e..8e97252df41 100644 --- a/new-page-template.md +++ b/new-page-template.md @@ -35,7 +35,7 @@ this guide show you how to do?" and "why would someone want to do this?". You need: -- A Kubernetes cluster with [Knative installed](../install/README.md). - Anything else? @@ -83,6 +83,6 @@ If your guide installs a sample application, show the user how to delete it. Provide links to other relevant topics, if applicable. Once someone has completed these steps, what might they want to do next? -- [Link](./page.md) -- [Link](./page.md) -- [Link](./page.md) +- [Link](./search.md) +- [Link](./search.md) +- [Link](./search.md) From 7da72f8b1c2033d146ccc05f2c7dc745fb6e2a0d Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Wed, 29 Apr 2020 12:17:31 -0700 Subject: [PATCH 4/4] Incorporate suggestions from abrennan89 --- CONTRIBUTING.md | 86 ++++++++++++++++++++++++++----------------------- 1 file changed, 46 insertions(+), 40 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 029cbe90c5f..4cf28f3d6e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,9 +14,10 @@ propose changes to this document in a pull request. ### Code of conduct -Knative follows the [Knative Code of Conduct](https://github.com/knative/community/blob/master/CODE-OF-CONDUCT.md). By -participating, you are expected to uphold this code. Please report unacceptable -behavior to knative-code-of-conduct@googlegroups.com. +Knative follows the +[Knative Code of Conduct](https://github.com/knative/community/blob/master/CODE-OF-CONDUCT.md). +By participating, you are expected to uphold this code. Please report +unacceptable behavior to knative-code-of-conduct@googlegroups.com. ### Contributor license agreements @@ -30,16 +31,16 @@ necessary because you own the copyright to your changes, even after your contribution becomes part of this project. So this agreement simply gives us permission to use and redistribute your contributions as part of the project. -Note: Your contributions are verified using the email address for which you -use to sign the CLA. Therefore, +Note: Your contributions are verified using the email address for which you use +to sign the CLA. Therefore, [setting your GitHub account to private](https://help.github.com/en/articles/setting-your-commit-email-address) -is unsupported because all commits from private accounts are sent from the `noreply` -email address. +is unsupported because all commits from private accounts are sent from the +`noreply` email address. ### Style guide Knative documentation follows the -[Google Developer Documentation Style Guide](https://developers.google.com/style/); +[Google Developer Documentation Style Guide](https://developers.google.com/style/). Use this as a reference for writing style questions. use it as a reference for writing style questions. ## Contributing to the documentation @@ -71,18 +72,19 @@ issue in the [`knative/website`repo](https://github.com/knative/website/issues). ### Working group -The [Knative Documentation Working Group](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md#documentation) -meets weekly on Tuesdays and alternates between a 9am PT and a 4:30pm PT time to -accommodate contributors in both the EMEA and APAC timezones. +The +[Knative Documentation Working Group](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md#documentation) +meets biweekly on Tuesdays at 9:30am PT. [Click here](https://calendar.google.com/calendar/embed?src=google.com_18un4fuh6rokqf8hmfftm5oqq4%40group.calendar.google.com) -to see the exact dates on the Knative working group calendar. If you're -interested in becoming more involved in Knative's documentation, start attending -the working group meetings. You'll meet the writers currently steering our -documentation efforts, who are happy to help you get started. +to see the exact dates on the Knative working group calendar. + +If you're interested in becoming more involved in Knative's documentation, start +attending the working group meetings. You'll meet the writers currently steering +our documentation efforts, who are happy to help you get started. ### Getting started -There are a couple different ways to jump in to the Knative doc set: +There are a couple of different ways to get started with contributing to the Knative documentation: - Look for a [Good First Issue](https://github.com/knative/docs/labels/kind%2Fgood-first-issue) @@ -96,25 +98,25 @@ There are a couple different ways to jump in to the Knative doc set: [friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging) of your experience and then use that to open your first set of PRs. Examples: - - What was hard for you? - - Did you stumble on something because it wasn't clear? + - What was difficult for you? + - Did you stumble on something because the steps weren't clear? - Was a dependency not mentioned? **A few pointers and other considerations** -- Think about how you can improve the documentation as a whole.
For - example, how can you fix the issue you found so that others don't run into the - same challenges? +- Think about how you can improve the documentation as a whole. For example, how + can you fix the issue you found so that others don't run into the same + challenges? -- Are there multiple places that could be fixed? +- Are there multiple places the issue could be fixed? - - Are there other pages that you should apply your update? + - Are there other pages which you should also update? - - Would it help if there was a link to more or related information on a the - page? On a related page? + - Would it help if there was a link to more or related information on a page? + On a related page? - Was the title or description misleading? Did you expect to find something - else? + different in that docs section? - If you find something and don't have the bandwidth to open a PR, make us aware of the pain point and open an @@ -194,8 +196,8 @@ There are currently two categories of user-focused code samples, _Knative owned and maintained_ and _Community owned and maintained_. - **Knative owned and maintained**: Includes code samples that are actively - maintained and e2e tested. To ensure content currency and balance available - resource, only the code samples that meet the following requirements are + maintained and e2e tested. To ensure content is current and balance available + resources, only the code samples that meet the following requirements are located in the `docs/[*component*]/samples` folders of the `knative/docs` repo: @@ -259,32 +261,34 @@ in the product, or for a fix or update existing content. 1. Add one or more `cherrypick-#.#` labels to that PR to indicate which of the past release branches should also be fixed. Generally, we only maintain the most recent numbered release. - 1. If you want to complete the fix yourself (**best practice**), you then open a - subsequent PR by running `git cherry-pick [COMMIT#]` against the - `release-0.5`. - Where `[COMMIT#]` is the commit of the PR that you merged in `master`. + 1. If you want to complete the fix yourself (**best practice**), you then + open a subsequent PR by running `git cherry-pick [COMMIT#]` against the + `release-0.5`. Where `[COMMIT#]` is the commit of the PR that you merged + in `master`. Note: Depending on workload and available bandwidth, one of the Knative team members might be able to help handle the `git cherry-pick` in order to push the fix into the affected release branch(es). See a list of the available documentation versions in the -[branches page](https://github.com/knative/docs/branches) -of the `knative/docs` repo. +[branches page](https://github.com/knative/docs/branches) of the `knative/docs` +repo. ## Assigning owners and reviewers For both documentation and code samples, you should assign your PR to a single -owner ("_Assignee_"). It's best to set the "Assignee" and include other -stakeholders as "Reviewers" rather than leaving it unassigned or allowing -[Prow](https://prow.k8s.io/command-help) to auto assign reviewers. +owner ("_Assignee_") using the `/assign` Prow command. It's best to set the +"Assignee" and include other stakeholders as "Reviewers" rather than leaving it +unassigned or allowing [Prow](https://prow.k8s.io/command-help) to auto assign +reviewers. Use the `/assign` command to set the owner. For example: `/assign @owner_id` For code samples, initially set the owner of your PR to the SME who should review for technical accuracy. If you don't know who the appropriate owner is, nor who your reviewers should be for your PR, you can assign the -[current working group lead](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md) of the related component. +[current working group lead](https://github.com/knative/community/blob/master/working-groups/WORKING-GROUPS.md) +of the related component. If you want to notify and include other stakeholders in your PR review, use the `/cc` command. For example: `/cc @stakeholder_id1 @stakeholder_id2` @@ -295,7 +299,8 @@ Because contributing to the documentation requires a different skill set than contributing to the Knative code base, we've defined the roles of documentation contributors separately from the roles of code contributors. -If you're looking for code contributor roles, see [ROLES](https://github.com/knative/community/blob/master/ROLES.md). +If you're looking for code contributor roles, see +[ROLES](https://github.com/knative/community/blob/master/ROLES.md). ### Member @@ -409,4 +414,5 @@ to become an approver at a meeting of the Documentation Working Group. Once you feel you meet the criteria, you can ask one of the current approvers to nominate you to become an approver. If all existing approvers agree that you meet the criteria open a PR to add yourself as a docs-approver in the -[OWNERS_ALIASES](https://github.com/knative/docs/tree/master/OWNERS_ALIASES) file. +[OWNERS_ALIASES](https://github.com/knative/docs/tree/master/OWNERS_ALIASES) +file.