Reorganise docs contributor guide (knative#4489)

* Reorganise contributing docs

* Fix whitespace

* Fix typo

* Tweak wording

* Fix formatting

* Update CONTRIBUTING.md

* Update DEVELOPMENT.md

* lint

* lint

* Fix broken link

* Fix link

* Update README.md

* Update README.md

* fix link

* Tweaks

* Update formatting.md

* Update github-workflow.md

* Remove info about Website repo

* Remove link to community website

* Update previewing-docs-locally.md

* Fix formatting

* Fix links

* Remove preview for blog

* Fix formatting

CONTRIBUTING.md

@@ -1,13 +1,3 @@
 
-All information about contributing to the Knative documentation has been moved
-into a single location:
-
-#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/docs/help/)
-
-**Quick links**:
-* [Docs help](https://knative.dev/docs/help/contributor/)
-    * New content templates:
-        * [Concept](docs/help/contributor/templates/template-concept.md)
-        * [Procedure](docs/help/contributor/templates/template-procedure.md)
-        * [Troubleshooting](docs/help/contributor/templates/template-troubleshooting.md)
-        * [Blog](docs/help/contributor/templates/template-blog-entry.md)
+All information about contributing to the Knative documentation has been moved to the
+**[How-to guides for Knative docs contributors](contribute-to-docs/README.md)**.

DEVELOPMENT.md

@@ -1,20 +1,3 @@
----
-_build:
-  render: never
-  list: never
----
-(This guide only appears on GitHub, not the website, because it
-**intentionally** does not include YAML front-matter.)
 
-All information about contributing to the Knative documentation has been moved
-into a single location:
-
-#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/docs/help/)
-
-**Quick links**:
-   * [Docs help](https://knative.dev/docs/help/contributor/)
-      * New content templates:
-         * [Concept](docs/help/contributor/templates/template-concept.md)
-         * [Procedure](docs/help/contributor/templates/template-procedure.md)
-         * [Troubleshooting](docs/help/contributor/templates/template-troubleshooting.md)
-         * [Blog](docs/help/contributor/templates/template-blog-entry.md)
+All information about contributing to the Knative documentation has been moved to the
+**[How-to guides for Knative docs contributors](contribute-to-docs/README.md)**.

README.md

@@ -24,9 +24,9 @@ The Knative website includes versioned docs for recent releases, the Knative
 blog, links to all community resources, as well as Knative governance and
 contributor guidelines.
 
-### Run website locally
+### Run the website locally
 
-For instructions, see Knative's [MkDocs contributor guide](https://knative.dev/docs/help/contributor/mkdocs-contributor-guide).
+For instructions, see Knative's [docs contributor guide](contribute-to-docs/getting-started/previewing-docs-locally.md).
 
 ### Website source files
 
@@ -55,22 +55,22 @@ reading about how to contribute to the docs, you should take a moment to learn
 about the Knative code of conduct, governance, values, and the various working
 groups and committees.
 
-[Knative community and contributor guidelines](https://knative.dev/community/contributing/)
+[Knative community and contributor guidelines](https://github.com/knative/community/)
 
 Source files for all Knative community and governance topics are located
 separately in the [knative/community](https://github.com/knative/community/)
 repo.
 
 To help you get started, see the following resources:
 
-- [Knative docs contributor's guide](https://knative.dev/docs/help/contributor/) -- Contains information about how
+- [Knative docs contributor's guide](contribute-to-docs/README.md) -- Contains information about how
   to contribute.
 
 - New content templates:
-  - [Concept](docs/help/contributor/templates/template-concept.md)
-  - [Procedure](docs/help/contributor/templates/template-procedure.md)
-  - [Troubleshooting](docs/help/contributor/templates/template-troubleshooting.md)
-  - [Blog](docs/help/contributor/templates/template-blog-entry.md)
+  - [Concept](contribute-to-docs/templates/template-concept.md)
+  - [Procedure](contribute-to-docs/templates/template-procedure.md)
+  - [Troubleshooting](contribute-to-docs/templates/template-troubleshooting.md)
+  - [Blog](contribute-to-docs/templates/template-blog-entry.md)
 
 ### Getting help
 

config/redirects.yml

@@ -104,7 +104,7 @@ plugins:
       eventing/sources/containersource.md: eventing/custom-event-source/containersource/README.md
       eventing/sources/pingsource/index.md: eventing/sources/ping-source/README.md
       eventing/triggers/index.md: eventing/broker/triggers/README.md
-      help/README.md: help/contributor/README.md
+      help/contributor/README.md: https://github.com/knative/docs/blob/main/contribute-to-docs/README.md
       install/collecting-logs/index.md: serving/observability/logging/collecting-logs.md
       install/collecting-metrics/index.md: serving/observability/metrics/collecting-metrics.md
       install/getting-started-knative-app/index.md: getting-started/README.md

contribute-to-docs/README.md

@@ -0,0 +1,41 @@
+# Knative docs contributor guide
+
+## Getting started
+
+- [Code of Conduct](https://github.com/knative/community/blob/main/CODE-OF-CONDUCT.md)
+- [Becoming a contributor](getting-started/becoming-a-contributor.md)
+- [GitHub workflow for Knative documentation](getting-started/github-workflow.md)
+- [Previewing the website locally](getting-started/previewing-docs-locally.md)
+- [Formatting content](getting-started/formatting.md)
+- [Navigation and redirects](getting-started/navigation-and-redirects.md)
+- [Branches and cherrypicking](getting-started/branches-and-cherrypicking.md)
+
+
+## What to contribute
+
+- [Creating new documentation](what-to-contribute/creating-new-docs.md)
+- [Creating blog posts](what-to-contribute/creating-blog-posts.md)
+- [Creating code samples](what-to-contribute/creating-code-samples.md)
+
+
+## Templates
+
+- [Blog entry template](templates/template-blog-entry.md)
+- [Concept template](templates/template-concept.md)
+- [Procedure template](templates/template-procedure.md)
+- [Troubleshooting template](templates/template-troubleshooting.md)
+
+
+## Style
+
+You don't need to read the whole style guide before contributing to Knative documentation.
+Unpolished contributions delivered early are better than perfect contributions delivered late.
+
+If you notice gaps in the style guide or have queries, please post in [the Docs Slack channel](https://knative.slack.com/archives/C9CV04DNJ).
+
+- [Documenting code](style-guide/documenting-code.md)
+- [Formatting standard and conventions](style-guide/style-and-formatting.md)
+- [Voice and language](style-guide/voice-and-language.md)
+- [Word and phrase list](style-guide/word-and-phrase-list.md)
+- [Content re-use](style-guide/content-reuse.md)
+- Using shortcodes (TBD)

contribute-to-docs/getting-started/README.md

@@ -0,0 +1,15 @@
+# Getting started contributing to Knative docs
+
+This folder contains information you need to get started contributing to Knative documentation.
+If you have any questions, contact us on the [#docs channel on Knative Slack](https://slack.knative.dev).
+We're happy to help!
+
+Table of contents:
+
+- [Code of Conduct](https://github.com/knative/community/blob/main/CODE-OF-CONDUCT.md)
+- [Becoming a contributor](becoming-a-contributor.md)
+- [GitHub workflow for Knative documentation](github-workflow.md)
+- [Previewing the website locally](previewing-docs-locally.md)
+- [Formatting content](formatting.md)
+- [Navigation and redirects](navigation-and-redirects.md)
+- [Branches and cherrypicking](branches-and-cherrypicking.md)

docs/help/contributor/becoming-a-contributor.md → contribute-to-docs/getting-started/becoming-a-contributor.md

@@ -5,7 +5,7 @@
 You must meet the following prerequisites before you are able to contribute to
 the docs. The following steps are specific to docs contributions.
 For more information about contributing to the Knative project, see the
-[Knative contribution guidelines](https://github.com/knative/community/blob/main/contributing.md).
+[Knative contribution guidelines](https://github.com/knative/community/blob/main/CONTRIBUTING.md).
 
 1. If you don't already have an account, you must create
    [a new GitHub account](https://github.com/join).
@@ -69,7 +69,7 @@ Knative documentation:
 - Attend a Documentation working group meeting
   -- Come join us to ask questions, get help, and meet other docs contributors.
 
-  [See meeting details, times, and the agenda](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md#documentation)
+  [See meeting details, times, and the agenda](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md#documentation--user-experience)
 
 ## Workflow overview
 
@@ -98,3 +98,11 @@ also ask a few clarifying questions, or add details such as diagrams or notes if
 needed. It's not necessarily expected that tech writers will actually execute
 the steps of a tutorial — it's expected that the SME is responsible for a
 working tutorial or how-to.
+
+## Further resources
+
+For further resources to help you to contribute to Knative documentation, see
+the [Knative docs contributor guide README](../README.md).
+
+For more information about Knative's values and processes, see the
+[community repo](https://github.com/knative/community).

contribute-to-docs/getting-started/branches-and-cherrypicking.md

@@ -0,0 +1,65 @@
+# Branches and cherrypicking
+
+Knative attempts to [support the last 4 releases](https://github.com/knative/community/blob/main/mechanics/RELEASE-VERSIONING-PRINCIPLES.md).
+
+By default, new documentation should be written on the `main` branch and then
+cherry-picked to the release branches if needed. Note that the default view of
+[Knative website](https://knative.dev/) is of the most recent release branch, which means that
+changes to `main` don't show up unless explicitly cherrypicked. This also
+means that documentation changes for a release _should be made during the
+development cycle_, rather than at the last minute or after the release.
+
+
+## Docs versioning
+
+Each version of the Knative docs are separated by branches in the `knative/docs`
+repository. The `main` branch represents the "in active development" version
+of the docs. All content in the `main` branch is renders on the
+[Knative website](https://knative.dev/) under
+the **Pre-release** menu and might not be tested nor working.
+
+Content in all the other branches of the `knative/docs` repo
+represent "released versions of the docs" and use the naming convention
+`release-#.#` where `#.#` is the version of Knative to which those docs
+correspond.
+
+
+## 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 `main`
+  branch. All pre-release content for active Knative development belongs in
+  [`main`](https://github.com/knative/docs/tree/main/).
+
+- **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 cherrypick your PR.
+  Add the "`cherrypick` labels" to your
+  original PR to indicate in which of the past release that your change affects.
+
+See a list of the available documentation versions in the
+[branches page](https://github.com/knative/docs/branches) of the `knative/docs`
+repo.
+
+
+## Cherrypicking
+
+You can use the [`/cherrypick` tool](https://github.com/kubernetes/test-infra/tree/master/prow/external-plugins/cherrypicker#cherrypicker)
+to automatically cherrypick changes from `main` to previous releases.
+
+For example, if you find a typo in a page of the `v1.0` release, then that
+page in the `main` branch likely also has that typo.
+
+To fix the typo:
+
+1.  Open a PR against the
+    [`main`](https://github.com/knative/docs/tree/main/) branch.
+1.  In a comment on your PR, use the
+    [`/cherrypick` tool](https://github.com/kubernetes/test-infra/tree/master/prow/external-plugins/cherrypicker#cherrypicker)
+    to indicate which of the past release branches should also be fixed. Generally, we only
+    maintain the most recent numbered release.
+
+After the original PR is merged, the /cherrypick tool automatically creates a
+new PR with your changes on the specified branch.