Salvage old contributor docs

.github/pull-request-template.md

@@ -9,14 +9,14 @@ your original PR has been merged into the main branch. Once the cherry-pick PR
 has merged, remove the cherry-pick label from the original PR.
 
 Use one of the new content templates:
-- [Concept](./template-concept.md) -- Conceptual topics explain how things work or what things mean.
-They provide helpful context to readers. They do not include procedures.
-- [Procedure](./template-procedure.md) -- Procedural (how-to) topics include detailed steps to
-perform a task as well as some context about the task.
-- [Troubleshooting](./template-troubleshooting.md) -- Troubleshooting topics list common errors and
-solutions.
-- [Blog](./template-blog-entry.md) -- Instructions and a template that you can use to help you post
-to the Knative blog.
+- [Concept](./docs/contributor/templates/template-concept.md) -- Conceptual topics explain how things
+work or what things mean. They provide helpful context to readers. They do not include procedures.
+- [Procedure](./docs/contributor/templates/template-procedure.md) -- Procedural (how-to) topics
+include detailed steps to perform a task as well as some context about the task.
+- [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md) -- Troubleshooting 
+topics list common errors and solutions.
+- [Blog](./docs/contributor/templates/template-blog-entry.md) -- Instructions and a template that you
+can use to help you post to the Knative blog.
 
 Consult [Knative contributor's guide](./help/contributing) for all resources for contributing to
 Knative documentation.

CONTRIBUTING.md

@@ -5,11 +5,11 @@ into a single location:
 #### [Go to the How-to guides for Knative docs contributors](https://knative.dev/help/)
 
 **Quick links**:
-   * [Docs help](https://knative.dev/help/contributor/)
-      * New content templates:
-        * [Concept](template-concept.md)
-        * [Procedure](template-procedure.md)
-        * [Troubleshooting](template-troubleshooting.md)
-        * [Blog](template-blog-entry.md)
-   * [Website help](https://knative.dev/help/contributor/publishing)
-   * [Maintainer help](https://knative.dev/help/maintainer/)
+* [Docs help](https://knative.dev/help/contributor/)
+    * New content templates:
+        * [Concept](./docs/contributor/templates/template-concept.md)
+        * [Procedure](./docs/contributor/templates/template-procedure.md)
+        * [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
+        * [Blog](./docs/contributor/templates/template-blog-entry.md)
+* [Website help](https://knative.dev/help/contributor/publishing)
+* [Maintainer help](https://knative.dev/help/maintainer/)

DEVELOPMENT.md

@@ -14,9 +14,9 @@ into a single location:
 **Quick links**:
    * [Docs help](https://knative.dev/help/contributor/)
       * New content templates:
-        * [Concept](template-concept.md)
-        * [Procedure](template-procedure.md)
-        * [Troubleshooting](template-troubleshooting.md)
-        * [Blog](template-blog-entry.md)
+         * [Concept](./docs/contributor/templates/template-concept.md)
+         * [Procedure](./docs/contributor/templates/template-procedure.md)
+         * [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
+         * [Blog](./docs/contributor/templates/template-blog-entry.md)
    * [Website help](https://knative.dev/help/contributor/publishing)
    * [Maintainer help](https://knative.dev/help/maintainer/)

README.md

@@ -66,10 +66,10 @@ We're excited that you're interested in contributing to the Knative documentatio
   to contribute.
 
 - New content templates:
-  - [Concept](template-concept.md)
-  - [Procedure](template-procedure.md)
-  - [Troubleshooting](template-troubleshooting.md)
-  - [Blog](template-blog-entry.md)
+  - [Concept](./docs/contributor/templates/template-concept.md)
+  - [Procedure](./docs/contributor/templates/template-procedure.md)
+  - [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
+  - [Blog](./docs/contributor/templates/template-blog-entry.md)
 
 ## Getting help
 

blog/README.md

@@ -13,9 +13,9 @@ into a single location:
 **Quick links**:
    * [Docs help](https://knative.dev/help/contributor/)
       * New content templates:
-        * [Concept](template-concept.md)
-        * [Procedure](template-procedure.md)
-        * [Troubleshooting](template-troubleshooting.md)
-        * [Blog](template-blog-entry.md)
+         * [Concept](./docs/contributor/templates/template-concept.md)
+         * [Procedure](./docs/contributor/templates/template-procedure.md)
+         * [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
+         * [Blog](./docs/contributor/templates/template-blog-entry.md)
    * [Website help](https://knative.dev/help/contributor/publishing)
    * [Maintainer help](https://knative.dev/help/maintainer/)

help/contributor/gettingstarted.md → docs/help/contributor/becoming-a-contributor.md

@@ -1,11 +1,4 @@
----
-title: "Joining the project and getting started"
-linkTitle: "Join"
-weight: 10
-type: "docs"
----
-
-
+# Becoming a contributor
 
 ## Join to become a contributor
 
@@ -57,9 +50,6 @@ Knative documentation:
 
 - Try out Knative and
   [send us feedback](https://github.com/knative/docs/issues/new?template=docs-feature-request.md).
-  For example, run through the [install guides](../../docs/install/) and then try
-  [Getting Started with Knative Serving](../../docs/serving/getting-started-knative-app.md)
-  or [Getting Started With Eventing](../../docs/eventing/getting-started.md).
 
   Keep a
   [friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging)
@@ -108,10 +98,3 @@ 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.
-
-## What's next
-
-- [Learn how to use GitHub and clone the `knative/docs` repo](./how-to/github.md)
-- [Read the "How to" guides](./how-to/)
-- [Learn how to post to the blog](./new-blog/)
-- [Learn how the website works](./publishing.md)

help/contributor/how-to/codesamples.md → docs/help/contributor/code-samples.md

@@ -1,9 +1,4 @@
----
-title: "Code samples"
-linkTitle: ""
-weight: 100
-type: "docs"
----
+# Code samples
 
 There are currently two general types of content that focus on code samples,
 either internal contributor content, or external-facing user content.

help/contributor/new-blog/_index.md → docs/help/contributor/creating-blog-posts.md

@@ -1,12 +1,6 @@
----
-title: "Creating blog posts"
-linkTitle: "New blog post"
-weight: 30
-type: "docs"
-showlandingtoc: "false"
----
+# Creating blog posts
 
-The Knative blog is owned by the [Documentation working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation) and run by the [Editorial Team](#leadership).
+The Knative blog is owned by the [DUX working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation--user-experience).
 
 This section covers documentation, processes, and roles for the [Knative blog](https://knative.dev/blog/).
 
@@ -41,7 +35,7 @@ To submit a blog post, follow the steps below.
 #### Suitable content:
 - **Original content only**
 - Knative [new feature releases and project updates](#communicating-new-project-releases)
-- Tutorials and demos [start a blog](./blog-page.md)
+- Tutorials and demos
 - Use cases
 - Content that is specific to a vendor or platform about Knative installation and use
 

help/contributor/new-docs/_index.md → docs/help/contributor/creating-new-docs.md

@@ -1,26 +1,25 @@
----
-title: "Adding new documentation"
-linkTitle: "New docs"
-weight: 20
-type: "docs"
-showlandingtoc: "false"
----
+# Creating new documentation
 
 To contribute new documentation, follow these steps:
 
 1. Identify the audience and intended use for the information.
 1. Choose the [type of content](#content-types) you wish to contribute.
-1. You can use a template to get started:
-   * [New docs file](./docs-page.md)
-   * [New `_index.md` file](./index-page.md)
+1. Use one of the new content templates:
+    - [Concept](templates/template-concept.md) -- Conceptual topics explain how
+    things work or what things mean. They provide helpful context to readers. They do not include
+    procedures.
+    - [Procedure](templates/template-procedure.md) -- Procedural (how-to) topics
+    include detailed steps to perform a task as well as some context about the task.
+    - [Troubleshooting](templates/template-troubleshooting.md) -- Troubleshooting
+    topics list common errors and solutions.
+    - [Blog](templates/template-blog-entry.md) -- Instructions and a template
+    that you can use to help you post to the Knative blog.
 1. [Choose appropriate titles and filenames](#choosing-titles-and-filenames).
-1. Write your new content. See the [How-to guides](/help/contributor/how-to/)
-   to help you with this process. Feel free to reach out to the
-   [Docs Working Group](/help/contributor/gettingstarted.md#get-help-from-the-community)
-   with any questions.
+1. Write your new content. See the [style guide](style-guide/README.md) to help you with this
+   process. Feel free to reach out to the
+   [DUX working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation--user-experience) with any questions.
 1. Open a PR in the [knative/docs GitHub repository](https://github.com/knative/docs)
-   to kick off the review process. For details, see our
-   [Using GitHub help](/help/contributor/how-to/github/#prs).
+   to kick off the review process. For details, see our [Using GitHub help](/github.md#prs).
 
 ## Identify the audience and intended use
 
@@ -30,9 +29,9 @@ determine the appropriate scope and depth of information to provide, its ideal
 structure, or the necessary supporting information. The following examples show
 this principle in action:
 
-- The reader needs to perform a specific task: Tell them how to recognize when
-  the task is necessary and provide the task itself as a list of numbered steps,
-  don’t simply describe the task in general terms.
+- The reader needs to perform a specific task. Tell them how to recognize when
+  the task is necessary, and provide the task itself as a list of numbered steps.
+  Don’t simply describe the task in general terms.
 
 - The reader must understand a concept before they can perform a task: Before
   the task, tell them about the prerequisite information and provide a link to
@@ -58,8 +57,8 @@ giving readers all the information you have, because you are unsure about
 what information they need.
 
 If you need help identifying the audience for you content, we are happy to help
-and answer all your questions during the [Docs Working Group](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md)
-biweekly meetings.
+and answer all your questions during the [DUX working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation--user-experience)
+weekly meetings.
 
 ## Content types
 
@@ -77,7 +76,7 @@ their intended audiences, and the goals each type strives to achieve:
         </tr>
     </thead>
     <tr>
-      <td>Concepts</td>
+      <td>Concept</td>
       <td>Explain some significant aspect of Knative. For example, a concept page
       describes the configuration model of a feature and explains its functionality.
       Concept pages don't include sequences of steps. Instead, provide links to
@@ -86,7 +85,7 @@ their intended audiences, and the goals each type strives to achieve:
       knowledge of the project.</td>
     </tr>
     <tr>
-      <td>Reference pages</td>
+      <td>Reference</td>
       <td>Provide exhaustive and detailed technical information. Common examples
       include API parameters, command-line options, configuration settings, and
       advanced procedures. Reference content is generated from the Knative code
@@ -96,7 +95,7 @@ their intended audiences, and the goals each type strives to achieve:
       needs specific bits of information to complete advanced tasks.</td>
     </tr>
     <tr>
-      <td>Examples</td>
+      <td>Example</td>
       <td>Describe a working and stand-alone example that highlights a set of
       features, an integration of Knative with other projects, or an end-to-end
       solution for a use case. Examples must use an existing Knative setup as a
@@ -107,23 +106,23 @@ their intended audiences, and the goals each type strives to achieve:
       to produce their own solutions.</td>
     </tr>
     <tr>
-      <td>Tasks</td>
-      <td>Shows how to achieve a single goal using Knative features. Tasks contain procedures written
-      as a sequence of steps. Tasks provide minimal
+      <td>Procedure</td>
+      <td>Shows how to achieve a single goal using Knative features. Procedures are written
+      as a sequence of steps. Procedures provide minimal
       explanation of the features, but include links to the concepts that
-      provide the related background and knowledge. Tasks must include automated
+      provide the related background and knowledge. Procedures must include automated
       tests since they are tested and maintained for technical accuracy.</td>
       <td>Readers that want to use Knative features.</td>
     </tr>
     <tr>
-      <td>Setup pages</td>
+      <td>Setup</td>
       <td>Focus on the installation steps needed to complete an Knative
       deployment. Setup pages must include automated tests since they are tested and maintained for technical accuracy.
       </td>
       <td>New and existing Knative users that want to complete a deployment.</td>
     </tr>
     <tr>
-      <td>Blog posts</td>
+      <td>Blog</td>
       <td>
         Focus on Knative or products and technologies related to it. Blog posts fall in one of the following three categories:
         <ul>
@@ -136,15 +135,15 @@ their intended audiences, and the goals each type strives to achieve:
       about it in an anecdotal, experiential, and more informal way.</td>
     </tr>
     <tr>
-      <td>News entries</td>
+      <td>News</td>
       <td>
         Focus on timely information about Knative and related events. News entries typically announce new releases or upcoming events.
       </td>
       <td>Readers that want to quickly learn what's new and what's happening in
       the Knative community.</td>
     </tr>
     <tr>
-      <td>FAQ entries</td>
+      <td>FAQ</td>
       <td>
         Provide quick answers to common questions. Answers don't introduce any
         concepts. Instead, they provide practical advice or insights. Answers
@@ -154,7 +153,7 @@ their intended audiences, and the goals each type strives to achieve:
       resources to learn more.</td>
     </tr>
     <tr>
-      <td>Operation guides</td>
+      <td>Operation guide</td>
       <td>
         Focus on practical solutions that address specific problems encountered while running Knative in a real-world setting.
       </td>
@@ -171,7 +170,7 @@ search engines to find and use sentence style capitalization.
 
 #### New files
 
-The filename of your new content should reflect that the title.
+The filename of your new content should reflect the title.
 
 #### New files and folders
 
@@ -183,12 +182,7 @@ a new folder if you are adding multiple topics/files, or if you are grouping
 related content. The names for each file do not need to repeat the folder name
 since that context is already established.
 
-For more guidance, see the
-[Headings and titles](https://developers.google.com/style/headings) section in
-the style guide.
-
-
 ## Submit your contribution to GitHub
 
-If you are not familiar with GitHub, see our [working with GitHub guide](../how-to/github.md)
+If you are not familiar with GitHub, see our [working with GitHub guide](/github.md)
 to learn how to submit documentation changes.

help/contributor/how-to/github.md → docs/help/contributor/github.md

@@ -1,21 +1,9 @@
----
-title: "GitHub workflow for Knative documentation"
-linkTitle: "Using GitHub"
-weight: 10
-type: "docs"
----
+# GitHub workflow for Knative documentation
 
 Learn how to use GitHub and contribute to the `knative/docs` repo.
 
-At a high-level, you must setup and know the following to get started:
 
-- [Set up your local machine](#clone)
-- [Open Issues](#issues)
-- [Create Pull Requests](#prs)
-- [Manage PRs and Issues with Prow](#prow)
-
-
-## Set up your local machine{#clone}
+## Set up your local machine
 
 To check out your fork of the `knative/docs` repository:
 
@@ -42,7 +30,7 @@ You are now able to open PRs, start reviews, and contribute fixes the
 [syncing your fork](https://help.github.com/articles/syncing-a-fork/).
 
 
-## Reporting documentation issues{#issues}
+## Report documentation issues
 
 <!-- This could use a pass to reduce the overhead for filing new issues,
 and to consolidate items more easily during issue triage. -->
@@ -77,7 +65,7 @@ the issue in the
 [`knative/website` repo](https://github.com/knative/website/issues).
 
 
-## Fixing documentation issues (Opening PRs){#prs}
+## Open PRs to fix documentation issues
 
 The Knative documentation follows the standard
 [GitHub collaboration flow](https://guides.github.com/introduction/flow/)
@@ -171,7 +159,7 @@ If you want to notify and include other stakeholders in your PR review, use the
 [See the Knative community guidelines about reviewing PRs](https://github.com/knative/community/blob/main/reviewing.md)
 
 
-## Using Prow to manage PRs and Issues{#prow}
+## Using Prow to manage PRs and Issues
 
 Knative uses several sets of tools to manage pull requests (PR)s and issues in a
 more fine-grained way than GitHub permissions allow. In particular, you'll
@@ -202,3 +190,18 @@ the known commands:
 
 - See the [Branches](./structure/#branches) section for details about how
   to use the `/cherrypick` command.
+
+### Common GitHub PRs FAQs
+
+* The CLA check fails even though you have signed the CLA. This may occur if you accept and commit
+suggestions in a pull request from another person's account, because the email address of that
+account doesn't match the address on record for the CLA.
+The commit will show up as co-authored, which can cause issues if your public email address has not
+signed the CLA.
+
+* One or more tests are failing. If you do not see a specific error related to a change you made,
+and instead the errors are related to timeouts, try re-running the test at a later time.
+There are running tasks that could result in timeouts or rate limiting if your test runs at the same
+time.
+
+* Other Issues/Unsure -- reach out in the #docs Slack channel and someone will be happy to help out.