diff --git a/.github/pull-request-template.md b/.github/pull-request-template.md index 9125c5a82c6..8bef5dec4d3 100644 --- a/.github/pull-request-template.md +++ b/.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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fed77805ca..bdc71a8a1f3 100644 --- a/CONTRIBUTING.md +++ b/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/) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e4a54199d0c..2c23b6703c6 100644 --- a/DEVELOPMENT.md +++ b/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/) diff --git a/README.md b/README.md index 2fa47dafc5c..4edb3f23106 100644 --- a/README.md +++ b/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 diff --git a/blog/README.md b/blog/README.md index f25514044c2..21fd129de37 100644 --- a/blog/README.md +++ b/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/) diff --git a/help/contributor/gettingstarted.md b/docs/help/contributor/becoming-a-contributor.md similarity index 88% rename from help/contributor/gettingstarted.md rename to docs/help/contributor/becoming-a-contributor.md index dd894ad16fa..7ebe311b225 100644 --- a/help/contributor/gettingstarted.md +++ b/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) diff --git a/help/contributor/how-to/codesamples.md b/docs/help/contributor/code-samples.md similarity index 98% rename from help/contributor/how-to/codesamples.md rename to docs/help/contributor/code-samples.md index 20a86e77de4..b5304d8896a 100644 --- a/help/contributor/how-to/codesamples.md +++ b/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. diff --git a/help/contributor/new-blog/_index.md b/docs/help/contributor/creating-blog-posts.md similarity index 91% rename from help/contributor/new-blog/_index.md rename to docs/help/contributor/creating-blog-posts.md index 2b6f889a4ce..2d47570c195 100644 --- a/help/contributor/new-blog/_index.md +++ b/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 diff --git a/help/contributor/new-docs/_index.md b/docs/help/contributor/creating-new-docs.md similarity index 78% rename from help/contributor/new-docs/_index.md rename to docs/help/contributor/creating-new-docs.md index bbcf9a51576..55663f9c5ba 100644 --- a/help/contributor/new-docs/_index.md +++ b/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: - Concepts + Concept 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. - Reference pages + Reference 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. - Examples + Example 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. - Tasks - Shows how to achieve a single goal using Knative features. Tasks contain procedures written - as a sequence of steps. Tasks provide minimal + Procedure + 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. Readers that want to use Knative features. - Setup pages + Setup 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. New and existing Knative users that want to complete a deployment. - Blog posts + Blog Focus on Knative or products and technologies related to it. Blog posts fall in one of the following three categories: