Rewrite contribution guides to empower reviewers (istio#6358)

* Rewrite contribution guides to empower reviewers

This rewrite includes the following changes:

- Implement the new reviewer role.
- Restructure the contribution guides into multiple smaller pages to make
  them easier to reference.
- Added separate pages for adding new content and reviewing content.
- Added clarifying text for the implemented shortcodes and processes.
- Updated all links.
- Added color-coded flow chart of the review process.

Signed-off-by: rcaballeromx <grca@google.com>

* Add content to help identify audience needs.

Addressed typos, consistency improvements, and other small fixes.
Added a mention and link to our code of conduct to the review process.

Signed-off-by: rcaballeromx <grca@google.com>

.spelling

@@ -115,8 +115,8 @@ Brooks
 bt
 Budinsky
 c.f.
+callout
 callouts
-Callouts
 camelCase
 canaried
 canarying
@@ -245,6 +245,7 @@ GKE-Istio
 GKE-Workloads
 GlueCon
 Gmail
+GoLang
 googleapis.com
 googlegroups.com
 Grafana
@@ -327,6 +328,7 @@ Kube
 kubebuilder
 KubeCon
 kubeconfig
+kubectl
 Kubelet
 kubelet
 Kubernetes
@@ -472,6 +474,7 @@ reimplemented
 reinject
 repurposed
 rethink
+reusability
 Reviewer1
 Reviewer2
 roadmap
@@ -502,12 +505,15 @@ sha256
 sharded
 Sharding
 sharding
+shortcode
+shortcodes
 Shriram
 sidecar
 sidecar.env
 SignalFX
 sinkInfo
 SLOs
+SMEs
 Snell-Feikema
 SNI
 SolarWinds
@@ -551,6 +557,7 @@ timeframe
 timestamp
 TLS
 TLS-secured
+ToC
 touchpoints
 Trulia
 trustability

content/en/about/contribute/_index.md

@@ -1,8 +1,28 @@
 ---
-title: Contributing to the Docs
-description: Learn how to contribute to improve and expand the Istio documentation.
-weight: 100
+title: Contribute Documentation to Istio
+description: Details how to create and maintain documentation pages.
+weight: 1
 aliases:
+    - /docs/welcome/contribute/writing-a-new-topic.html
     - /docs/welcome/contribute/index.html
+    - /docs/reference/contribute/writing-a-new-topic.html
+    - /about/contribute/writing-a-new-topic.html
+    - /about/contribute/creating-and-editing-pages
+    - /create
+keywords: [contribute, github, docs, shortcodes, code-blocks, website]
+list_below: true
 icon: contribute
 ---
+
+Welcome to the Istio documentation contribution guides. This section contains
+all the information you need to contribute documentation, blog posts, and other
+[content types](/about/contribute/add-content/#content-types).
+
+The Istio content is multilingual. Within the `content` folder, you can
+find the following folders for the available languages:
+
+- The English original content is in the `en` folder.
+- The Mandarin translation is in the `zh` folder.
+- The Portuguese translation is in the `pt-br` folder.
+
+Learn more in the following guides:

content/en/about/contribute/add-content/index.md

@@ -0,0 +1,179 @@
+---
+title: Add New Documentation
+description: Details how to contribute new documentation to Istio.
+weight: 3
+aliases:
+    - /docs/welcome/contribute/writing-a-new-topic.html
+    - /docs/reference/contribute/writing-a-new-topic.html
+    - /about/contribute/writing-a-new-topic.html
+    - /create
+keywords: [contribute]
+---
+
+To contribute new documentation to Istio, just 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. [Choose a title](#choosing-a-title).
+1. Write your contribution following our [documentation contribution guides](/about/contribute).
+1. Submit your contribution to our [GitHub repository](https://github.com/istio/istio.io).
+1. Follow our [review process](/about/contribute/review) until your contribution
+   is merged.
+
+## Identify the audience and intended use
+
+The best documentation starts by knowing the intended readers, their knowledge,
+and what you expect them to do with the information. Otherwise, you cannot
+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 must understand a concept before they can perform a task: Before
+  the task, tell them about the prerequisite information and provide a link to
+  it.
+
+- The reader needs to make a decision: Provide the conceptual information
+  necessary to know when to make the decision, the available options, and when
+  to choose one option instead of the other.
+
+- The reader is an administrator but not a SWE: Provide a script,
+  not a link to a code sample in a developer’s guide.
+
+- The reader needs to extend the features of the product: Provide an example of
+  how to extend the feature, using a simplified scenario for illustration
+  purposes.
+
+- The reader needs to understand complex feature relationships: Provide a
+  diagram showing the relationships, rather than writing multiple pages of
+  content that is tedious to read and understand.
+
+The most important thing to avoid is the common mistake of simply
+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/istio/community/blob/master/WORKING-GROUPS.md#istio-working-groups)
+biweekly meetings.
+
+## Content types
+
+When you understand the audience and the intended use for the information you
+provide, you can choose content type that best addresses their needs. To make it
+easy for you to choose, the following table shows the supported content types,
+their intended audiences, and the goals each type strives to achieve:
+
+<table>
+    <thead>
+        <tr>
+            <th>Content type</th>
+            <th>Goals</th>
+            <th>Audiences</th>
+        </tr>
+    </thead>
+    <tr>
+      <td>Concepts</td>
+      <td>Explain some significant aspect of Istio. 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
+      corresponding tasks.</td>
+      <td>Readers that want to understand how features work with only basic
+      knowledge of the project.</td>
+    </tr>
+    <tr>
+      <td>Reference pages</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 Istio code
+      base and tested for accuracy.
+      </td>
+      <td>Readers with advanced and deep technical knowledge of the project that
+      needs specific bits of information to complete advanced tasks.</td>
+    </tr>
+    <tr>
+      <td>Examples</td>
+      <td>Describe a working and stand-alone example that highlights a set of
+      features, an integration of Istio with other projects, or an end-to-end
+      solution for a use case. Examples must use an existing Istio setup as a
+      starting point. Examples must include an automated test since they are maintained for technical accuracy.
+      </td>
+      <td>Readers that want to quickly run the example themselves and
+      experiment. Ideally, readers should be able to easily change the example
+      to produce their own solutions.</td>
+    </tr>
+    <tr>
+      <td>Tasks</td>
+      <td>Shows how to achieve a single goal using Istio features. Tasks contain procedures written
+      as a sequence of steps. Tasks provide minimal
+      explanation of the features, but include links to the concepts that
+      provide the related background and knowledge. Tasks must include automated
+      tests since they are tested and maintained for technical accuracy.</td>
+      <td>Readers that want to use Istio features.</td>
+    </tr>
+    <tr>
+      <td>Setup pages</td>
+      <td>Focus on the installation steps needed to complete an Istio
+      deployment. Setup pages must include automated tests since they are tested and maintained for technical accuracy.
+      </td>
+      <td>New and existing Istio users that want to complete a deployment.</td>
+    </tr>
+    <tr>
+      <td>Blog posts</td>
+      <td>
+        Focus on Istio or products and technologies related to it. Blog posts fall in one of the following three categories:
+        <ul>
+        <li>Posts detailing the author’s experience using and configuring Istio, especially those that articulate a novel experience or perspective.</li>
+        <li>Posts highlighting Istio features.</li>
+        <li>Posts detailing how to accomplish a task or fulfill a specific use case using Istio. Unlike Tasks and Examples, the technical accuracy of blog posts is not maintained and tested after publication.</li>
+        </ul>
+      </td>
+      <td>Readers with a basic understanding of the project who want to learn
+      about it in an anecdotal, experiential, and more informal way.</td>
+    </tr>
+    <tr>
+      <td>News entries</td>
+      <td>
+        Focus on timely information about Istio 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 Istio community.</td>
+    </tr>
+    <tr>
+      <td>FAQ entries</td>
+      <td>
+        Provide quick answers to common questions. Answers don't introduce any
+        concepts. Instead, they provide practical advice or insights. Answers
+        must link to tasks, concepts, or examples in the documentation for readers to learn more.
+      </td>
+      <td>Readers with specific questions who are looking for brief answers and
+      resources to learn more.</td>
+    </tr>
+    <tr>
+      <td>Operation guides</td>
+      <td>
+        Focus on practical solutions that address specific problems encountered while running Istio in a real-world setting.
+      </td>
+      <td>Service mesh operators that want to fix problems or implement
+      solutions for running Istio deployments.</td>
+    </tr>
+  </table>
+
+## Choosing a title
+
+Choose a title for your topic that has the keywords you want search engines to
+find. All content files in Istio are named `index.md`, but each content file is
+within a folder that uses the keywords in the topic's title,
+separated by hyphens, all in lowercase. Keep folder names as short as possible
+to make cross-references easier to create and maintain.
+
+## Submit your contribution to GitHub
+
+If you are not familiar with GitHub, see our [working with GitHub guide](/about/contribute/github)
+to learn how to submit documentation changes.
+
+If you want to learn more about how and when your contributions are published,
+see the [section on branching](/about/contribute/github#branching-strategy) to understand
+how we use branches and cherry picking to publish our content.

content/en/about/contribute/build/index.md

@@ -0,0 +1,91 @@
+---
+title: Build and serve the website locally
+description: Explains how to locally build, test, serve, and preview the website.
+weight: 5
+keywords: [contribute, serve, Docker, Hugo, build]
+---
+
+After making your contribution to our website, ensure the changes
+render as you expect. To ensure you can preview your changes locally, we have
+tools that let you build and view them easily. We use automated tests to check
+the quality of all contributions. Before submitting your changes in a Pull
+Request (PR), you should run the tests locally too.
+
+## Before you begin
+
+To guarantee the tests you run locally use the same versions as the tests
+running on the Istio Continuous Integration (CI), we provide a Docker image with
+all the tools needed, including our site generator: [Hugo](https://gohugo.io/).
+
+To build, test, and preview the site locally, you need to install
+[Docker](https://www.docker.com/get-started) on your system.
+
+## Preview your changes
+
+To preview your changes to the site, go to the root of your fork of
+`istio/istio.io` and run the following command:
+
+{{< text bash >}}
+$ make serve
+{{< /text >}}
+
+If your changes have no build errors, the command builds the site and starts a
+local web server to host it. To see the local build of the site, go to
+`http://localhost:1313` on your web browser.
+
+If you need to make and serve the site from a remote server, you can use
+`ISTIO_SERVE_DOMAIN` to provide the IP address or DNS Domain of the server, for
+example:
+
+{{< text bash >}}
+$ make ISTIO_SERVE_DOMAIN=192.168.7.105 serve
+{{< /text >}}
+
+The example builds the site and starts a web server, which hosts the site on the
+remote server at the `192.168.7.105` IP address. Like before, you can then
+connect to the web server at `http://192.168.7.105:1313`.
+
+### Test your changes
+
+We use linters and tests to ensure a quality baseline for the site's content
+through automated checks. These checks must pass without failure for us to
+approve your contribution. Make sure you run the checks locally before you
+submit your changes to the repository through a PR. We perform the following
+automated checks:
+
+- HTML proofing: ensures all links are valid along with other checks.
+
+- Spell check: ensures content is spelled correctly.
+
+- Markdown Style check: ensures the markup used complies with our Markdown style
+  rules.
+
+To run these checks locally, use the following command:
+
+{{< text bash >}}
+$ make lint
+{{< /text >}}
+
+If the spell checker reports errors, the following are the most likely causes:
+
+- A real typo: Fix the typo on your Markdown files.
+
+- The error is reported for a command, field, or symbol name: Place
+  \`back-ticks\` around the content with the error.
+
+- The error is reported for a correct word or proper name not present in the
+  tool's dictionary: Add the word to the `.spelling` file at the root of the
+  `istio/istio.io` repository.
+
+Due to poor Internet connectivity, you could have trouble with the link checker.
+If you can't get good connectivity, you can set the checker to prevent it from
+checking external links. Set the `INTERNAL_ONLY` environment variable to `True`
+when running the linter, for example:
+
+{{< text bash >}}
+$ make INTERNAL_ONLY=True lint
+{{< /text >}}
+
+When your content passes all the checks, submit it to the repository through a
+PR. Visit [Working with GitHub](/about/contribute/github) for more
+information.