Consolidate all "docs" help info into single location (#3437)

* consolidate docs how-to guides * fix template linking * consolidate and organize * update links * fix link * fix typos and offensive term * Update help/contributor/how-to/formatting.md Co-authored-by: Samia Nneji <[email protected]> * Update help/contributor/how-to/formatting.md Co-authored-by: Samia Nneji <[email protected]> * Update help/contributor/gettingstarted.md Co-authored-by: Samia Nneji <[email protected]> * Update help/faqs.md Co-authored-by: Samia Nneji <[email protected]> * Update help/contributor/publishing.md Co-authored-by: Samia Nneji <[email protected]> * Update help/contributor/publishing.md Co-authored-by: Samia Nneji <[email protected]> * recover review comments * typo Co-authored-by: Samia Nneji <[email protected]>
knative · Apr 26, 2021 · 3af9db6 · 3af9db6
1 parent e3170d4
commit 3af9db6
Show file tree

Hide file tree

Showing 31 changed files with 2,258 additions and 636 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -6,54 +6,17 @@ _build:
 (This guide only appears on GitHub, not the website, because it
 **intentionally** does not include YAML front-matter.)
 
-# Development
-
-This doc explains how to setup a development environment so you can get started
-[contributing](https://www.knative.dev/contributing/) to `Knative Docs`. Also
-take a look at:
-
-- [The pull request workflow](https://www.knative.dev/contributing/contributing/#pull-requests)
-
-## Prerequisites
-
-Follow the instructions below to set up your development environment. Once you
-meet these requirements, you can make changes and
-
-Before submitting a PR, see also [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-### Sign up for GitHub
-
-Start by creating [a GitHub account](https://github.com/join), then setup
-[GitHub access via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/).
-
-### Checkout your fork
-
-To check out this repository:
-
-1. Create your own
-   [fork of this repo](https://help.github.com/articles/fork-a-repo/)
-1. Clone it to your machine:
-
-```shell
-mkdir -p ${GOPATH}/src/knative.dev
-cd ${GOPATH}/src/knative.dev
-git clone [email protected]:${YOUR_GITHUB_USERNAME}/docs.git
-cd docs
-git remote add upstream https://github.com/knative/docs.git
-git remote set-url --push upstream no_push
-```
-
-_Adding the `upstream` remote sets you up nicely for regularly
-[syncing your fork](https://help.github.com/articles/syncing-a-fork/)._
-
-### Run website locally
-
-Refer to this [doc](https://github.com/knative/website/blob/main/DEVELOPMENT.md) in the website repo.
-
-### Common Troubleshooting issues for PRs
-
-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.
-
-1. Other Issues/Unsure - reach out in the #docs slack channel and someone will be happy to help out.
+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/help/)
+
+**Quick links**:
+   * [Docs help](https://knative.dev/help/contributor/)
+      * New content templates:
+        * [Documentation](https://github.com/knative/docs/tree/main/template-docs-page.md) -- Instructions and a template that
+          you can use to help you add new documentation.
+        * [Blog](https://github.com/knative/docs/tree/main/template-blog-page.md) -- Instructions and a template that
+          you can use to help you post to the Knative blog.
+   * [Website help](https://knative.dev/help/contributor/publishing)
+   * [Maintainer help](https://knative.dev/help/maintainer/)
diff --git a/blog/README.md b/blog/README.md
@@ -1,65 +1,21 @@
+=======
 ---
 _build:
   render: never
   list: never
 ---
 
-# Knative blog
+All information about contributing to the Knative documentation has been moved
+into a single location:
 
-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).
+#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/help/)
 
-This section covers documentation, processes, and roles for the [Knative blog](https://knative.dev/blog/).
-
-## Leadership
-
-- **Technical Editors:** [Lionel Villard](https://github.com/lionelvillard), [Evan Anderson](https://github.com/evankanderson)
-- **Copy Editors:** [Ashleigh Brennan](https://github.com/abrennan89), [Caroline Lee](https://github.com/carieshmarie), [María Cruz](https://github.com/macruzbar)
-- **Blog Community Managers:**  [María Cruz](https://github.com/macruzbar), [Jonatas Baldin](https://github.com/jonatasbaldin)
-
-## Contact
-
-- Slack: [#docs](https://knative.slack.com/archives/C9CV04DNJ)
-
-## Submit a Post
-
-Anyone can write a blog post and submit it for review. Commercial content is not allowed. Please refer to the [blog guidelines](#blog-guidelines) for more guidance.
-
-To submit a blog post, follow the steps below.
-
-1. [Sign the Contributor License Agreements](https://github.com/knative/community/blob/main/CONTRIBUTING.md#contributor-license-agreements) if you have not yet done so.
-1. Familiarize yourself with the Markdown format for existing blog posts in the [docs repository](https://github.com/knative/docs/tree/main/blog). Blog posts are categorized into different directories. You can explore the directories to find examples.
-1. Write your blog post in a text editor of your choice.
-1. (Optional) If you need help with markdown, check out [StakEdit](https://stackedit.io/app#) or read [GitHub's formatting syntax](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) for more information.
-1. Choose a directory in the [docs repository](https://github.com/knative/docs/tree/main/blog), and click **Create new file**.
-1. Paste your content into the editor and save it. Name the file in the following way: *[BLOG] Your proposed title* , but don’t put the date in the file name. The blog reviewers will work with you on the final file name, and the date on which the blog will be published.
-1. When you save the file, GitHub will walk you through the pull request (PR) process.
-1. A reviewer is assigned to all pull requests automatically. The reviewer checks your submission, and works with you on feedback and final details. When the pull request is approved, the blog will be scheduled for publication.
-1. Ping editorial team members on Slack [#docs](https://knative.slack.com/archives/C9CV04DNJ) channel with a link to your recently created PR.
-
-### Blog Guidelines
-
-#### Suitable content:
-- **Original content only**
-- Knative [new feature releases and project updates](## Communicating new project releases)
-- Tutorials and demos [start a blog](https://github.com/knative/docs/pull/2511)
-- Use cases
-- Content that is specific to a vendor or platform about Knative installation and use
-
-#### Unsuitable Content:
-- Blogs that do not address Knative in any way
-- Content that doesn't interact with Knative APIs or interfaces
-- Vendor pitches
-
-## Communicating new project releases
-**Scheduled releases:** The Knative project has a release every 6 weeks, and we need your help communicating new changes to our community! If you would like to contribute a blog post to the Knative blog, please consider writing about the latest changes to the project. Ideally, there should be a single blog post for every release version, for example, 0.17; 0.18; 0.19. The title convention should be: *Version [version number] release - [date]*. Release blog contributors should write a summary of the changes and select up to 3 highlights of the current release to write about.
-**Big changes to the project.** Big changes to the project require a deep dive blog that describes the new feature in detail and give examples of the new functionality.  
-
-## Review Process
-
-After a blog post is submitted as a PR, it is automatically assigned to a reviewer.
-
-Each blog post requires a `lgtm` label from at least one person in the editorial team. Once the necessary labels are in place, one of the reviewers will add an `approved` label, and schedule publication of the blog post.
-
-### Service level agreement (SLA)
-
-Blog posts can take up to **1 week** to review. If you'd like to request an expedited review, please say so on your message when you ping the editorial team on Slack.
+**Quick links**:
+   * [Docs help](https://knative.dev/help/contributor/)
+      * New content templates:
+        * [Documentation](https://github.com/knative/docs/tree/main/template-docs-page.md) -- Instructions and a template that
+          you can use to help you add new documentation.
+        * [Blog](https://github.com/knative/docs/tree/main/template-blog-page.md) -- Instructions and a template that
+          you can use to help you post to the Knative blog.
+   * [Website help](https://knative.dev/help/contributor/publishing)
+   * [Maintainer help](https://knative.dev/help/maintainer/)
diff --git a/docs/reference/api/README.md b/docs/reference/api/README.md
@@ -1,3 +1,4 @@
+
 ## View the latest release
 
 The reference documentation for the latest release of the Knative is available
@@ -10,118 +11,8 @@ The API source files are located at:
 - [Serving API](./serving.md)
 - [Eventing API](./eventing/eventing.md)
 
-## Updating API Reference docs (for Knative maintainers)
-
-The Knative API reference documentation is manually generated using the
-[`gen-api-reference-docs.sh`](../../../hack/) tool. If you need to generate a new
-version of the API docs for a recent update or for a new release, you can use
-the following steps.
-
-To learn more about the tool, see the
-[gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs)
-reference page.
-
-### Before you begin
-
-You must meet the following requirements to run the `gen-api-reference-docs.sh`
-tool:
-
-- You need the following software installed:
-  - [`git`](https://git-scm.com/download/)
-  - [`go` version 1.11+](https://golang.org/dl/)
-- Clone [knative/docs](https://github.com/knative/docs) locally. For example:
-  `git clone [email protected]:knative/docs.git`
-
-### Generating the API
-
-To generate a version of the API:
-
-1. Ensure that your `GOPATH` is empty. The `gen-api-reference-docs.sh` script
-   will result in the `GOPATH should not be set` error if your `GOPATH` is
-   configured. You view the value by running the following command:
-
-   ```
-   echo $GOPATH
-   ```
-
-   If your `GOPATH` is already configured, temporarily clear the `GOPATH` value
-   by running the following command:
-
-   ```
-   export GOPATH=""
-   ```
-
-1. Locate the commits or tags that correspond to the version of the API that you
-   want to generate:
-
-   - [Serving](https://github.com/knative/serving/releases/)
-   - [Eventing](https://github.com/knative/eventing/releases/)
-
-1. To run the `gen-api-reference-docs.sh` command from the `hack` directory, you
-   specify the commits or tags for each of the corresponding Knative component
-   variables (`KNATIVE_[component_name]_COMMIT`):
-
-   ```
-   cd hack
-
-   KNATIVE_SERVING_COMMIT=[commit_or_tag] \
-   KNATIVE_EVENTING_COMMIT=[commit_or_tag] \
-   ./gen-api-reference-docs.sh
-   ```
-
-   where `[commit_or_tag]` is the commit or tag in the specific repo that
-   represents the version of the API that you want to generate. Also see the
-   [example](#example) below.
-
-   **Result**
-
-   The `gen-api-reference-docs.sh` tool generates the API in a `tmp` folder.
-   After a successful build, the tool automatically opens that folder in the
-   `tmp` directory.
-
-   If the script fails, there are a couple possible causes.
-
-   * If you get the
-     `F1116 15:21:23.549503   63473 main.go:129] no API packages found in ./pkg/apis`
-     error, check if a new version of the script is available:
-      https://github.com/ahmetb/gen-crd-api-reference-docs/tags
-
-      The script is kept up-to-date with changes that go into the Kubernetes API.
-      As Knative adds support for those APIs, you might need to make sure the
-      corresponding
-      [script `gen-crd-api-reference-docs` version](https://github.com/knative/docs/blob/main/hack/gen-api-reference-docs.sh#L26)
-      is used.
-
-   * If you get the
-     `F0807 13:58:20.621526 168834 main.go:444] type invalid type has kind=Unsupported which is unhandled`
-     error, the import target might have moved. There might be other causes for that error but view
-     [#2054](https://github.com/knative/docs/pull/2054) (and the linked Issues) for details about how we handled that error
-     in the past.
-
-1. Copy the generated API files into the `docs/reference` directory of your
-   knative/docs clone.
-
-1. The linter now fails for content with trailing whitespaces. Use a tool of your choice to
-   remove all trailing whitespace. For example, search for and remove: `\s+$`
-
-You can now perform the necessary steps to open a PR, complete a review, and
-merge the new API files into the appropriate branch of the `knative/docs` repo.
-See the [contributor flow](/DOCS-CONTRIBUTING.md) for details
-about requesting changes in the `knative/docs` repo.
-
-### Example
-
-To build a set of Knative API docs for v0.18, you can use the `v0.18.0` the tags
-from each of the Knative component repositories, like
-[Serving v0.18.0](https://github.com/knative/serving/tree/v0.18.0). If you want to
-use a commit for Serving v0.18.0, you would use
-[850b7c](https://github.com/knative/serving/commit/850b7cca7d7701b052420a030f2308d19938d45e).
-
-Using tags from each repo, you would run the following command to generate the
-v0.18.0 API source files:
+### Generating API docs
 
-```
-KNATIVE_SERVING_COMMIT=v0.18.0 \
-KNATIVE_EVENTING_COMMIT=v0.18.0 \
-./gen-api-reference-docs.sh
-```
+See the
+[API build instructions](https://www.knative.dev/help/maintainer/building-api-output)
+in the Knative documentation maintainer section.
diff --git a/docs/smoketest.md b/docs/smoketest.md
@@ -1,7 +1,3 @@
-# Spacer Title
-
-<br>
-
 # Hidden smoketest page
 
 Use this page to test your changes and ensure that there are not any issues,
@@ -30,9 +26,14 @@ Below are a set of site elements that have causes issues in the past.
 The following use the
 [`readfile` shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md)
 
+Shortcode: <code>{<code>{< readfile file="../hack/reference-docs-gen-config.json" code="true" lang="json" >}</code>}</code>
+   renders as:
 {{< readfile file="../hack/reference-docs-gen-config.json" code="true" lang="json" >}}
 
-{{< readfile file="../Gopkg.toml" code="true" lang="toml" >}}
+Shortcode: <code>{<code>{< readfile file="./serving/samples/cloudevents/cloudevents-nodejs/service.yaml" code="true" lang="yaml" >}</code>}</code>
+   renders as:
+{{< readfile file="./serving/samples/cloudevents/cloudevents-nodejs/service.yaml" code="true" lang="yaml" >}}
+
 
 ## Install version numbers and Clone branch commands
 
@@ -42,27 +43,46 @@ added in-line with the
 (uses the define values from
 [config/\_default/params.toml](https://github.com/knative/website/blob/main/config/_default/params.toml))
 
-1. Shortcode: <code>{<code>{% version %}</code>}</code>
+1. Shortcode: <code>{<code>{< version >}</code>}</code>
+   renders as: {{< version >}}
 
    Example:
-   `kubectl apply version/{{% version %}}/is-the-latest/docs-version.yaml`
+   `kubectl apply version/{{< version >}}/is-the-latest/docs-version.yaml`
 
-1. Shortcode: <code>{<code>{% version override="v0.2.2" %}</code>}</code>
+1. Shortcode: <code>{<code>{< version override="v0.2.2" >}</code>}</code>
+    renders as: {{< version override="v0.2.2" >}}
 
    Example:
-   `kubectl apply the-version-override/{{% version override="v0.2.2" %}}/is-manually-specified.yaml`
+   `kubectl apply the-version-override/{{< version override="v0.2.2" >}}/is-manually-specified.yaml`
 
-1. Shortcode: <code>{<code>{% version patch=".20" %}</code>}</code>
+1. Shortcode: <code>{<code>{< version patch=".20" >}</code>}</code>
+    renders as: {{< version patch=".20" >}}
 
    Example:
-   `kubectl apply this-is-a-point-release/{{% version patch=".20" %}}/filename.yaml`
+   `kubectl apply this-is-a-point-release/{{< version patch=".20" >}}/filename.yaml`
 
-1. Shortcode: <code>{<code>{% branch %}</code>}</code>
+1. Shortcode: <code>{<code>{< branch >}</code>}</code>
+    renders as: {{< branch >}}
 
    Example:
-   `git clone -b "{{% branch %}}" https://github.com/knative/docs knative-docs`
+   `git clone -b "{{< branch >}}" https://github.com/knative/docs knative-docs`
 
-1. Shortcode: <code>{<code>{% branch override="release-0.NEXT" %}</code>}</code>
+1. Shortcode: <code>{<code>{< branch override="release-0.NEXT" >}</code>}</code>
+    renders as: {{< branch override="release-0.NEXT" >}}
 
    Example:
-   `git clone -b "{{% branch override="release-0.NEXT" %}}" https://github.com/knative/docs knative-docs`
+   `git clone -b "{{< branch override="release-0.NEXT" >}}" https://github.com/knative/docs knative-docs`
+
+## Tabs
+
+How to include tabbed content in your page. Note that you can set a default tab.
+
+{{< tabs name="tabs_example" default="Include example" >}}
+{{< tab name="Regular example" >}}
+This is a regular example tab.
+{{< /tab >}}
+
+{{< tab name="Include example" >}}
+{{% readfile file="./serving/samples/multi-container/service.yaml" code="true" lang="yaml" %}}
+{{< /tab >}}
+{{< /tabs >}}
diff --git a/help/_index.md b/help/_index.md
@@ -0,0 +1,21 @@
+---
+title: "How-to guides for contributing to Knative documentation"
+linkTitle: "How-to guides for docs"
+weight: "10"
+type: "docs"
+showlandingtoc: "true"
+---
+
+<!-- Original file: https://github.com/knative/docs/pull/3269 -->
+
+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
@@ -0,0 +1,10 @@
+---
+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.