From 21fe8c783ac0024d7b6f07cc3fc7f0e60d43255e Mon Sep 17 00:00:00 2001 From: RichardJJG Date: Fri, 16 Jul 2021 13:32:09 +0100 Subject: [PATCH] Salvage old contributor docs (#4020) * Culled old contributor docs * Fixed links * Fix links to templates * Revert "Fix links to templates" This reverts commit 2025fed68eafa3828fb4172f0ac7104f474d8f00. * Fixes for template links * Revert "Fixes for template links" This reverts commit 691cdcc96597abe5541eb131b49362b3dd48b685. * Some fixes for the template links * Revert "Some fixes for the template links" This reverts commit a1762749c4a57d3d95267ac0ce1f06f51afa5ded. * Removed broken links * Fixed link to style guide readme * Remove faulty link to style guide * Update docs/help/contributor/creating-new-docs.md Co-authored-by: Ashleigh Brennan * Update docs/help/contributor/creating-new-docs.md Co-authored-by: Ashleigh Brennan * Changed Docs WG references and some punctuation * Added links * Revert "Added links" This reverts commit cb5ddb759bddd30572adbf7b9737a99564d26ea7. * Moved templates and changed links * Fixing links Co-authored-by: Ashleigh Brennan --- .github/pull-request-template.md | 16 +- CONTRIBUTING.md | 16 +- DEVELOPMENT.md | 8 +- README.md | 8 +- blog/README.md | 8 +- .../contributor/becoming-a-contributor.md | 19 +- .../help/contributor/code-samples.md | 7 +- .../help/contributor/creating-blog-posts.md | 12 +- .../help/contributor/creating-new-docs.md | 74 ++++--- .../help/contributor}/github.md | 37 ++-- .../help/contributor}/structure.md | 9 +- .../templates/template-blog-entry.md | 0 .../contributor/templates/template-concept.md | 0 .../templates/template-procedure.md | 2 +- .../templates/template-troubleshooting.md | 0 help/README.md | 20 -- help/contributor/_index.md | 10 - help/contributor/how-to/_index.md | 7 - help/contributor/how-to/formatting.md | 113 ----------- help/contributor/how-to/frontmatter.md | 118 ----------- help/contributor/how-to/shortcodes.md | 56 ------ help/contributor/how-to/styleguide.md | 116 ----------- help/contributor/new-blog/blog-page.md | 10 - help/contributor/new-docs/docs-page.md | 10 - help/contributor/new-docs/index-page.md | 10 - help/contributor/publishing.md | 187 ------------------ help/faqs.md | 26 --- 27 files changed, 90 insertions(+), 809 deletions(-) rename help/contributor/gettingstarted.md => docs/help/contributor/becoming-a-contributor.md (88%) rename help/contributor/how-to/codesamples.md => docs/help/contributor/code-samples.md (98%) rename help/contributor/new-blog/_index.md => docs/help/contributor/creating-blog-posts.md (91%) rename help/contributor/new-docs/_index.md => docs/help/contributor/creating-new-docs.md (78%) rename {help/contributor/how-to => docs/help/contributor}/github.md (89%) rename {help/contributor/how-to => docs/help/contributor}/structure.md (97%) rename template-blog-entry.md => docs/help/contributor/templates/template-blog-entry.md (100%) rename template-concept.md => docs/help/contributor/templates/template-concept.md (100%) rename template-procedure.md => docs/help/contributor/templates/template-procedure.md (98%) rename template-troubleshooting.md => docs/help/contributor/templates/template-troubleshooting.md (100%) delete mode 100644 help/README.md delete mode 100644 help/contributor/_index.md delete mode 100644 help/contributor/how-to/_index.md delete mode 100644 help/contributor/how-to/formatting.md delete mode 100644 help/contributor/how-to/frontmatter.md delete mode 100644 help/contributor/how-to/shortcodes.md delete mode 100644 help/contributor/how-to/styleguide.md delete mode 100644 help/contributor/new-blog/blog-page.md delete mode 100644 help/contributor/new-docs/docs-page.md delete mode 100644 help/contributor/new-docs/index-page.md delete mode 100644 help/contributor/publishing.md delete mode 100644 help/faqs.md diff --git a/.github/pull-request-template.md b/.github/pull-request-template.md index 9125c5a82..8bef5dec4 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 8fed77805..bdc71a8a1 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 e4a54199d..2c23b6703 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 2fa47dafc..4edb3f231 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 f25514044..21fd129de 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 dd894ad16..7ebe311b2 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 20a86e77d..b5304d889 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 2b6f889a4..2d47570c1 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 bbcf9a515..55663f9c5 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:
    @@ -136,7 +135,7 @@ their intended audiences, and the goals each type strives to achieve: about it in an anecdotal, experiential, and more informal way. - News entries + News Focus on timely information about Knative and related events. News entries typically announce new releases or upcoming events. @@ -144,7 +143,7 @@ their intended audiences, and the goals each type strives to achieve: the Knative community. - FAQ entries + FAQ 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. - Operation guides + Operation guide Focus on practical solutions that address specific problems encountered while running Knative in a real-world setting. @@ -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. diff --git a/help/contributor/how-to/github.md b/docs/help/contributor/github.md similarity index 89% rename from help/contributor/how-to/github.md rename to docs/help/contributor/github.md index 8a7120c49..5bd455d14 100644 --- a/help/contributor/how-to/github.md +++ b/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 @@ -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. diff --git a/help/contributor/how-to/structure.md b/docs/help/contributor/structure.md similarity index 97% rename from help/contributor/how-to/structure.md rename to docs/help/contributor/structure.md index da43fbd1e..d6d8385ba 100644 --- a/help/contributor/how-to/structure.md +++ b/docs/help/contributor/structure.md @@ -1,9 +1,4 @@ ---- -title: "Content structure" -linkTitle: "" -weight: 20 -type: "docs" ---- +# Content structure **TODO: link to intended documentation layout.** A general warning about [Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law): documents will @@ -17,7 +12,7 @@ blog post, documentation within a code repo, or a vendor site may be the right place. Be generous with offering to link to such locations; documents in the main documentation come with an ongoing cost of keeping up to date. -[Learn about documenting code samples](./codesamples.md) +[Learn about documenting code samples](/code-samples.md) ## Branches diff --git a/template-blog-entry.md b/docs/help/contributor/templates/template-blog-entry.md similarity index 100% rename from template-blog-entry.md rename to docs/help/contributor/templates/template-blog-entry.md diff --git a/template-concept.md b/docs/help/contributor/templates/template-concept.md similarity index 100% rename from template-concept.md rename to docs/help/contributor/templates/template-concept.md diff --git a/template-procedure.md b/docs/help/contributor/templates/template-procedure.md similarity index 98% rename from template-procedure.md rename to docs/help/contributor/templates/template-procedure.md index 58e8d6260..bbd317b6d 100644 --- a/template-procedure.md +++ b/docs/help/contributor/templates/template-procedure.md @@ -211,7 +211,7 @@ If the note regards an issue that could lead to data loss, the note should be a The following is an embedded image reference in markdown. -![Annotated procedure topic](../images/annotated-procedure-topic.png) +![Annotated procedure topic](../../../images/annotated-procedure-topic.png) #### Tabs diff --git a/template-troubleshooting.md b/docs/help/contributor/templates/template-troubleshooting.md similarity index 100% rename from template-troubleshooting.md rename to docs/help/contributor/templates/template-troubleshooting.md diff --git a/help/README.md b/help/README.md deleted file mode 100644 index 1175bc05f..000000000 --- a/help/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "How-to guides for contributing to Knative documentation" -linkTitle: "How-to guides for docs" -weight: "10" -type: "docs" -showlandingtoc: "true" ---- - - - -Welcome to the *help* for Knative documentation. - -**First off, thanks for taking the time to contribute!** - -The following are guidelines for contributing to the user facing Knative -documentation, including help for new docs, blog posts, and other website -related information. - -These are just guidelines, not rules. Use your best judgment, and -feel free to open PRs and propose changes to these documents. diff --git a/help/contributor/_index.md b/help/contributor/_index.md deleted file mode 100644 index bbc0e844b..000000000 --- a/help/contributor/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Knative documentation contributor guides" -linkTitle: "Contributor guides" -weight: "10" -type: "docs" -showlandingtoc: "true" ---- - -Learn how to contribute content to the Knative documentation and publish -to the `knative.dev` website. diff --git a/help/contributor/how-to/_index.md b/help/contributor/how-to/_index.md deleted file mode 100644 index d7531902f..000000000 --- a/help/contributor/how-to/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "How-to for documentation" -linkTitle: "How-tos" -weight: "40" -type: "docs" -showlandingtoc: "true" ---- diff --git a/help/contributor/how-to/formatting.md b/help/contributor/how-to/formatting.md deleted file mode 100644 index 4e0a8faed..000000000 --- a/help/contributor/how-to/formatting.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Formatting standards and conventions" -linkTitle: "Formatting standards" -weight: 40 -type: "docs" ---- - -This page shows the formatting standards for the Knative documentation. Knative uses -Markdown to markup the content and Hugo with the Docsy template, to build the website. To ensure -consistency across our documentation, we have agreed on these formatting standards. - -[Learn about the Hugo/Docsy requirements for each page](./frontmatter.md) - -## Linking: Use relative URLs - -For all links within the Knative content, use relative linking (also known as -[relative URLs](https://www.w3.org/TR/WD-html40-970917/htmlweb.html#h-5.1.2)). - -Linking conventions: - - - Links between files in the same directory must be prefixed with: `./` - - Example: `[Shortcodes](./shortcodes.md)` renders as [Shortcodes](./shortcodes.md) - - - To link across folders, add `../` for each directory that you must travel - towards the root docs directory. - - Example: `[FAQs](../../faqs.md)` renders as [FAQs](../../faqs.md) - -#### Background - -Early on in the content development, all of the documentation was author in the -GitHub repos and since then, there are many contributors who value the ability -to consume the documentation from within the repo. In addition, the main -Markdown editor and renderer when authoring Knative docs is the GitHub UI. -Therefore, we continue to **use relative URLs throughout** to ensure that all -the links work as expected, both when clicked in the GitHub UI and on knative.dev. - -Hugo has it's own syntax for linking across your content and treats -the content across the site as a single version of docs (including a Hugo -specific definition of relative links: *relative to the website domain*). -Unfortunately, that type of linking renders markdown content unusable from with -the GitHub repos and does not allow for easy versioning/archiving. - -## Don't use capitalization for emphasis - -Only use the original capitalization found in the code or configuration files -when referencing those values directly. Use back-ticks \`\` around the -referenced value to make the connection explicit. For example, use -`IstioRoleBinding`, not `Istio Role Binding` or `istio role binding`. - -If you are not referencing values or code directly, use normal sentence -capitalization, for example, "The Knative role binding configuration takes place -in a YAML file." - -## Use angle brackets for placeholders - -Use angle brackets for placeholders in commands or code samples. Tell the reader -what the placeholder represents. For example: - - -1. Display information about a pod: - - $ kubectl describe pod - - Where `` is the name of one of your pods. - - -## Use **bold** to emphasize user interface elements - -|Do | Don't -|------------------|------ -|Click **Fork**. | Click "Fork". -|Select **Other**. | Select 'Other'. - -## Use _italics_ to emphasize new terms - -|Do | Don't -|-------------------------------------------|--- -|A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ... -|These components form the _control plane_. | These components form the **control plane**. - -Use the `gloss` shortcode and add glossary entries for new terms. - -## Use `back-ticks` around file names, directories, and paths - -|Do | Don't -|-------------------------------------|------ -|Open the `foo.yaml` file. | Open the foo.yaml file. -|Go to the `/content/en/docs/tasks` directory. | Go to the /content/en/docs/tasks directory. -|Open the `/data/args.yaml` file. | Open the /data/args.yaml file. - -## Use `back-ticks` around inline code and commands - -|Do | Don't -|----------------------------|------ -|The `foo run` command creates a `Deployment`. | The "foo run" command creates a `Deployment`. -|For declarative management, use `foo apply`. | For declarative management, use "foo apply". - -Use code-blocks for commands you intend readers to execute. Only use inline code -and commands to mention specific labels, flags, values, functions, objects, -variables, modules, or commands. - -* Learn how to include code snippets from source files using the - [`readfile`](https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md) - shortcode. See an [example](https://knative.dev/docs/smoketest/#code-samples). - -## Use `back-ticks` around object field names - -|Do | Don't -|-----------------------------------------------------------------|------ -|Set the value of the `ports` field in the configuration file. | Set the value of the "ports" field in the configuration file. -|The value of the `rule` field is a `Rule` object. | The value of the "rule" field is a `Rule` object. diff --git a/help/contributor/how-to/frontmatter.md b/help/contributor/how-to/frontmatter.md deleted file mode 100644 index dfc098714..000000000 --- a/help/contributor/how-to/frontmatter.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "Front matter" -linkTitle: "" -weight: 30 -type: "docs" ---- - -The front matter is YAML code in between triple-dashed lines at the top of each -file and provides important management options for our content. For example, the -front matter allows us to ensure that existing links continue to work for pages -that are moved or deleted entirely. This page explains the front matter -features that are currently available in knative.dev. - -The following example shows a front matter with all the required fields -filled by placeholders: - -``` ---- -title: "" -linkTitle: "" -weight: -type: "docs" -aliases: - - ---- -``` - -More details and options for Hugo frontmatter: https://gohugo.io/content-management/front-matter/#predefined - - -## Required front matter fields - -The following table shows descriptions for all the **required** fields: - - -|Field | Description -|-------------------|------------ -| `title` | The page's title. -| `linkTitle` | Optional: A short version of the page title that renders nicely in the navigation menu. -| `weight` | The order of the page relative to the other pages in the directory. -| `type` | Specify `docs`. Required for our docs versioning process. -| `aliases` | Optional: URLs of past pages that you want redirected to "this" page. - -[See how to define the Knative front matter](../new-docs/docs-page.md). - -### Rename, move, or delete pages - -When you move pages or delete them completely, you must ensure that the existing -links to those pages continue to work. The `aliases` field in the front matter -helps you meet this requirement. Add the path to the page before the move or -deletion to the `aliases` field. Hugo implements automatic redirects from the -old URL to the new URL for our users. - -On the _target page_, which is the page where you want users to land, add the `` -of the _original page_ to the front-matter as follows: - -``` -aliases: - - -``` - -### Example - -In this example, the following file is deleted: `/docs/install/knative-with-any-k8s.md` - -To ensure that anyone who tries to navigate to the deleted file gets redirected -to its replacement, you must add `/docs/install/knative-with-any-k8s.md` under -`aliases`. - -In the `/docs/install/_index.md` file, you add the -`/docs/install/knative-with-any-k8s` URL path without the file type suffix, -under `aliases`: - -``` ---- -title: "Installing Knative" -weight: 05 -type: "docs" -aliases: - - /docs/install/knative-with-any-k8s - - /docs/install/knative-with-aks - - /docs/install/knative-with-ambassador - - /docs/install/knative-with-contour - - /docs/install/knative-with-docker-for-mac - - /docs/install/knative-with-gke - - /docs/install/knative-with-gardener - - /docs/install/knative-with-gloo - - /docs/install/knative-with-icp - - /docs/install/knative-with-iks - - /docs/install/knative-with-microk8s - - /docs/install/knative-with-minikube - - /docs/install/knative-with-minishift - - /docs/install/knative-with-pks - - /docs/install/any-kubernetes-cluster -showlandingtoc: "false" ---- -``` - -Notice that multiple files redirect to the -`/docs/install/_index.md` file, all indented under `aliases`, prefixed with `-`, -and with paths starting from root. - -View the -[`docs/install/_index.md`](https://raw.githubusercontent.com/knative/docs/main/docs/install/_index.md) -file in the repository. - -## Optional front matter fields - -However, Hugo supports many front matter fields and this page only covers those -implemented on knative.dev. - -The following table shows the most commonly used **optional** fields: - -|Field | Description -|-------------------|------------ -|`linkTitle` | A shorter version of the title that is used to ensure that the text fits within the left navigation menu. -|`showlandingtoc`. | For `_index.md` files only. By default, an in-page TOC is added to the body of the page. Specify `"false"` to hide the in-page TOC. - diff --git a/help/contributor/how-to/shortcodes.md b/help/contributor/how-to/shortcodes.md deleted file mode 100644 index 1c9aa9f58..000000000 --- a/help/contributor/how-to/shortcodes.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Shortcodes: Website widgets" -linkTitle: "Shortcodes" -weight: "50" -type: "docs" ---- - -A list and examples of the custom shortcodes that are currently used and available in knative.dev. - -STATUS: This page is in "draft state" and needs to be completed. - - -## Knative custom shortcodes - -https://github.com/knative/website/tree/main/layouts/shortcodes - -All of these Knative shortcodes are added as examples in the smoketest pages - -- [root](https://knative.dev/smoketest/) -- [/docs/](https://knative.dev/docs/smoketest/) - - -## Learn more about shortcodes - - -- Hugo shortcodes https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes - - - How to create custom shortcodes https://gohugo.io/templates/shortcode-templates/ - -- Docsy shortcodes https://www.docsy.dev/docs/adding-content/shortcodes/ - -- Other shortcodes https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes - -### Includes - -Include files and code samples with the `readfile` shortcode: - -https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md - -### Dynamic variables - -Use them to reduce release maintenance and ensure content accuracy. - -The following variables are dynamically populated based on the URL of the content in knative.dev: - - - The [branch shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/branch.md) {{< branch >}} renders: `{{< branch >}}` - - The [version shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/version.md) {{< version >}} renders: `{{< version >}}` - -### Artifacts - -https://github.com/knative/website/pull/129/files - - -### Tabs - -https://github.com/knative/website/pull/124 diff --git a/help/contributor/how-to/styleguide.md b/help/contributor/how-to/styleguide.md deleted file mode 100644 index cd76e26da..000000000 --- a/help/contributor/how-to/styleguide.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: "Style guide" -linkTitle: "" -weight: 30 -type: "docs" ---- - -All content accepted into the Knative documentation must be **clear** and -**understandable**. Generally, content should aim to be "task oriented" and -thorough. - -The standard we use to make that determination is defined by -the [Google Developer Documentation Style -Guide](https://developers.google.com/style/). - -**Start here**: - -1. [Highlights](https://developers.google.com/style/highlights) -2. [General principles](https://developers.google.com/style/tone) -3. Use the sections below as reference. - -## Use sentence case for titles and headings - -Use sentence case for all titles and headings. Only capitalize the first -word of the heading, except for proper nouns or acronyms. - -|Do | Don't -|--------------------|----- -|Configuring feature | Configuring Feature -|Using feature. | Using Feature -|Using HTTPS | Using https - -## Use present tense - -|Do | Don't -|-----------------------------|------ -|This command starts a proxy. | This command will start a proxy. - -Exception: Use future or past tense if it is required to convey the correct -meaning. This exception is extremely rare and should be avoided. - -## Use active voice - -|Do | Don't -|-------------------------------------------|------ -|You can explore the API using a browser. | The API can be explored using a browser. -|The YAML file specifies the replica count. | The replica count is specified in the YAML file. - -## Use simple and direct language - -Use simple and direct language. Avoid using unnecessary phrases, such as saying -"please." - -|Do | |Don't -|----------------------------|--|---- -|To create a `ReplicaSet`, ... | | In order to create a `ReplicaSet`, ... -|See the configuration file. | | Please see the configuration file. -|View the Pods. | | With this next command, we'll view the Pods. - -## Address the reader as "you" - -|Do | Don't -|---------------------------------------|------ -|You can create a `Deployment` by ... | We'll create a `Deployment` by ... -|In the preceding output, you can see...| In the preceding output, we can see ... - -## Create useful links - -There are good hyperlinks, and bad hyperlinks. The common practice of calling -links *here* or *click here* are examples of bad hyperlinks. Check out [this -excellent article](https://medium.com/@heyoka/dont-use-click-here-f32f445d1021) -explaining what makes a good hyperlink and try to keep these guidelines in -mind when creating or reviewing site content. - -## Avoid using "we" - -Using "we" in a sentence can be confusing, because the reader might not know -whether they're part of the "we" you're describing. - -|Do | Don't -|------------------------------------------|------ -|Version 1.4 includes ... | In version 1.4, we have added ... -|Knative provides a new feature for ... | We provide a new feature ... -|This page teaches you how to use pods. | In this page, we are going to learn about pods. - -## Avoid jargon and idioms - -Some readers speak English as a second language. Avoid jargon and idioms to help -make their understanding easier. - -|Do | Don't -|----------------------|------ -|Internally, ... | Under the hood, ... -|Create a new cluster. | Turn up a new cluster. -|Initially, ... | Out of the box, ... - -## Avoid statements about the future - -Avoid making promises or giving hints about the future. If you need to talk -about a feature in development, add a boilerplate under the front matter that -identifies the information accordingly. - -### Avoid statements that will soon be out of date - -Avoid using wording that becomes outdated quickly like "currently" and -"new". A feature that is new today is not new for long. - -|Do | Don't -|------------------------------------|------ -|In version 1.4, ... | In the current version, ... -|The Federation feature provides ... | The new Federation feature provides ... - -## Other related items - -* [Page formatting standards](./formatting.md) -* [Include dynamic content with shortcodes](./shortcodes.md) diff --git a/help/contributor/new-blog/blog-page.md b/help/contributor/new-blog/blog-page.md deleted file mode 100644 index 35d6b6063..000000000 --- a/help/contributor/new-blog/blog-page.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -linkTitle: "Blog template" -weight: "30" -type: "docs" -aliases: - - "/template-blog-page" - - "/help/contributor/templates/template-blog-page" ---- - -{{% readfile file="/template-blog-entry.md" markdown="true" %}} diff --git a/help/contributor/new-docs/docs-page.md b/help/contributor/new-docs/docs-page.md deleted file mode 100644 index daa221a40..000000000 --- a/help/contributor/new-docs/docs-page.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -linkTitle: "Docs template" -weight: "10" -type: "docs" -aliases: - - "/template-docs-page" - - "/help/contributor/templates/template-docs-page" ---- - -{{% readfile file="/template-docs-page.md" markdown="true" %}} diff --git a/help/contributor/new-docs/index-page.md b/help/contributor/new-docs/index-page.md deleted file mode 100644 index 821c58a63..000000000 --- a/help/contributor/new-docs/index-page.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -linkTitle: "_index.md template" -weight: "50" -type: "docs" -aliases: - - "/template-_index-page" - - "/help/contributor/new-docs/template-_index-page" ---- - -{{% readfile file="/template-_index-page.md" markdown="true" %}} diff --git a/help/contributor/publishing.md b/help/contributor/publishing.md deleted file mode 100644 index ec17d9855..000000000 --- a/help/contributor/publishing.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: "Staging and publishing Knative documentation" -linkTitle: "Preview Website" -weight: "60" -type: "docs" ---- - -## Testing your documentation - -Before you kick off a PR review you can verify that: - -- The page and any elements like widgets, titles, and links, work and - renders correctly. -- If you moved or deleted a page, make sure to test that the redirects - (`aliases`) all work. - -### Auto PR preview builds - -All PRs are automatically built and a Preview is generated at: -https://app.netlify.com/sites/knative/deploys - -This is currently a manual process. - -1. Navigate to https://app.netlify.com/sites/knative/deploys -1. Click to view a build log. The list of build logs are ordered from - most recent to oldest. If you just pushed to your PR, then that build log is - near the top. -1. Scroll down to see the `PR#` in the log and verify that it's for your PR. -1. When you find the build log for your PR, click the **[Preview]** button to - view the unique build preview for your PR. - - **Important**: Each "event" in a Knative PR triggers a new/unique build - (Preview). Therefore, if you push a new commit, a new build with those - changes will appear at the top of https://app.netlify.com/sites/knative/deploys. - -### Local preview builds - -You can run a local preview of you fork. See the following setup section for -details about installing the required software. - -- Current supported Hugo version https://github.com/knative/website/blob/main/netlify.toml -- How to build knative.dev locally: Run [`https://github.com/knative/website/blob/main/scripts/localbuild.sh`](https://github.com/knative/website/blob/main/scripts/localbuild.sh) - -#### Setup the local requirements - -1. Clone this repo (or your fork) using `--recurse-submodules`, like so: - - ```bash - git clone --recurse-submodules https://github.com/knative/website.git - ``` - - If you accidentally cloned this repo without `--recurse-submodules`, you'll - need to do the following inside the repo: - - ```bash - git submodule init - git submodule update - cd themes/docsy - git submodule init - git submodule update - ``` - - (Docsy uses two submodules, but those don't use further submodules.) - -1. Clone the docs repo next to (_not inside_) the website repo. This allows you - to test docs changes alongside the website: - - ```bash - git clone https://github.com/knative/docs.git - ``` - - You may also want to clone the community repo: - - ```bash - git clone https://github.com/knative/community.git - ``` - -1. (Optional) If you want to change the CSS, install - [PostCSS](https://www.docsy.dev/docs/getting-started/#install-postcss) - -1. Install a supported version of [Hugo](https://www.docsy.dev/docs/getting-started/#install-hugo). - -#### Run locally - -You can use `./scripts/localbuild.sh` to build and test files locally. -The script uses Hugo's build and server commands in addition to some Knative -specific file scripts that enables optimal user experience in GitHub -(ie. use README.md files, allows our site to use relative linking -(not -[`rel` or `relref`](https://gohugo.io/content-management/cross-references/#use-ref-and-relref)), -etc.) and also meets Hugo/Docsy static site generator -and template requirements (ie. _index.hmtl files, etc.) - -The two local docs build options: - -- Simple/static HTML file generation for viewing how your Markdown renders in HTML: - - Use this to generate a static build of the documentation site into HTML. This - uses Hugo's build command [`hugo`](https://gohugo.io/commands/hugo/). - - From your clone of knative/website, you run `./scripts/localbuild.sh`. - - All of the HTML files are built into the `public/` folder from where you can open, - view, and test how each file renders. - - Notes: - - - This method does not mirror how knative.dev is generated and therefore is - only recommend to for testing how your files render. That also means that link - checking might not be 100% accurate. Hugo builds relative links differently - (all links based on the site root vs relative to the file in which the link - resides - this is part of the Knative specific file processing that is done) - therefore some links will not work between the statically built HTML files. - For example, links like `.../index.html` are converted to `.../` for simplicity - (servers treat them as the same destination) but when you are browsing a local HTML - file you need to open/click on the individual `index.html` files to get where you want - to go. - - This method does however make it easier to read or use local tools on the HTML build - output files (vs. fetching the HTML from the server). For example, it is useful for - refactoring/moving content and ensuring that complicated Markdown renders properly. - - Using this method also avoids the MacOs specific issue (see below), where the default - open FD limit exceeds the total number of `inotify` calls that Hugo wants to keep open. - -- Mimic how knative.dev is built and hosted: - - Use this option to locally build knative.dev. This uses Hugo's local server - command [`hugo server`](https://gohugo.io/commands/hugo_server/). - - From your clone of knative/website, you run `./scripts/localbuild.sh -s true`. - - All of the HTML files are temporarily copied into the `content/en/` folder to allow - the Hugo server to locally host those files at the URL:port specified in your terminal. - - Notes: - - - This method provides the following local build and test build options: - - test your locally cloned files - - build and test other user's remote forks (ie. locally build their PRs `./scripts/build.sh -f repofork -b branchname -s`) - - option to build only a specific branch or all branches (and also from any speicifed fork) - - fully functioning site links - - [See all command options in localbuild.sh](https://github.com/knative/website/blob/main/scripts/localbuild.sh) - - Hugo's live-reload is not completely utilized due to the required Knative specific file processing - scripts (you need to rerun `./scripts/localbuild.sh -s` to rebuild and reprocess any changes that you - make to the files from within your local knative/docs clone directory). - - Alternatively, if you want to use Hugo's live-reload feature, you can make temporary - changes to the copied files within the `content/en/` folder, and then when satisfied, you must - copy those changes into the corresponding files of your knative/docs clone. - - Files in `content/en/` are overwritten with a new copy of your local files in your knative/docs - clone folder each time that you run this script. Note that the last set of built files remain - in `content/en/` for you to run local tools against but are overwritten each time that you rerun the script. - - Using this method causes the MacOs specific issue (see below), where the default - open FD limit exceeds the total number of `inotify` calls that the Hugo server wants to keep open. - -## On a Mac - -If you want to develop on a Mac, you'll find two obstacles: - -### Sed - -The scripts assume GNU `sed`. You can install this with -[Homebrew](https://brew.sh/): - -```bash -brew install gnu-sed -# You need to put it in your PATH before the built-in Mac sed -PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH" -``` - -### File Descriptors in "server mode" - -By default, MacOS permits a very small number of open FDs. This will manifest -as: - -``` -ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files -``` - -You can fix this with the following (may be needed for each new shell): - -```bash -sudo launchctl limit maxfiles 65535 200000 -# Probably only need around 4k FDs, but 64k is defensive... -ulimit -n 65535 -sudo sysctl -w kern.maxfiles=100000 -sudo sysctl -w kern.maxfilesperproc=65535 -``` diff --git a/help/faqs.md b/help/faqs.md deleted file mode 100644 index afa3eccb6..000000000 --- a/help/faqs.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "FAQs and troubleshooting" -linkTitle: "FAQs" -weight: "100" -type: "docs" ---- - -A collection of FAQs from other docs contributors. - -### Common GitHub PRs FAQs - -1. 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. - -1. 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 - rerunning 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. - -### General troubleshooting - -1. Other Issues/Unsure - reach out in the #docs Slack channel and someone will - be happy to help out.