Add contribution docs to site and update roadmap

- Move the contribution guidelines to the documentation folder so they
  show up in the website. Some minor updates were introduced to reflect
  the agreements about documentation strategy.

- Update the roadmap. It now includes the main points agreed about the
  docs strategy going forward.

content/en/doc-con-main.md → content/en/docs/Contribute/_index.md

 <!--
 ---
-linkTitle: "Contributing to Tekton Documentation"
-weight: 1
+title: "Contribute to Documentation"
+linkTitle: "Contribute to Documentation"
+weight: 11
+description: > 
+  Contribution guidelines
 ---
 -->
-# Contributing to Tekton Documentation
 
 If you would like to contribute to Tekton documentation, we’re happy to have your help!
 Anyone can contribute, whether you’re new to the project or you’ve been around a long time,
 and whether you self-identify as a developer, an end user, or someone who just can’t stand
 seeing typos.
 
-This guide covers the following topics:
-
-- [Contribution types](#contribution-types)
-- [Contribution process](#contribution-process)
-- [Requesting a documentation improvement](#requesting-a-documentation-improvement)
-- [Submitting a documentation change](#submitting-a-documentation-change)
-- [I need help!](#i-need-help)
-
-Before you begin contributing, you should also read the following:
-
-- [Content guidelines for Tekton documentation](doc-con-content.md)
-- [Formatting conventions for Tekton documentation](doc-con-formatting.md)
-- [Writing high quality documentation for Tekton](doc-con-writing.md)
-
 ## Contribution types
 
 You can request an improvement by filing an issue or update the documentation yourself by
 filing a pull request against the relevant [Tekton repository](https://github.com/tektoncd).
-Assign your issue or pull request to @sergetron, Tekton's technical writer, for triage.
 
 Here's how we handle different types of documentation work:
 
@@ -51,22 +38,24 @@ content and link the pull request to it.
 **Note:** If you're creating a new page, make sure to include its proposed location within the
 Tekton documentation set.
 
-Assign the pull request and if applicable, the accompanying issue to @sergetron, Tekton's
-technical writer. The pull request then goes through technical and editorial review, and is
-published on the Tekton documentation website. Depending on our current workload, the review
-may take some time. Once the review is complete, the pull request is published to the Tekton
+Assign the pull request and if applicable, the accompanying issue to one of the
+[Tekton website approvers][approvers]. The pull request then goes through
+technical and editorial review, and is published on the Tekton documentation
+website. Depending on our current workload, the review may take some time. Once
+the review is complete, the pull request is published to the Tekton
 documentation site.
 
 Documentation contributions should be technically accurate and easy to understand. See the rest
 of this guide to learn how to produce clear, concise, and informative documentation.
 
+[approvers]: https://github.com/tektoncd/website/blob/main/OWNERS
+
 ## Requesting a documentation improvement
 
 **Example:** "You should document Tekton integration with Smurfcaptor.”
 
 If you found a problem with Tekton documentation but can't fix it yourself, you can request a
 documentation improvement by creating an issue against the relevant [Tekton repository](https://github.com/tektoncd)
-and assigning it to @sergetron, Tekton's technical writer.
 
 We evaluate the need to determine the scope of the requested content and an estimated delivery
 time based on our current workload. We then place the issue in the documentation queue.
@@ -92,8 +81,3 @@ to your new page to existing Tekton documentation.
 If you're not sure how to address a certain documentation issue, join the
 [#docs channel](https://app.slack.com/client/TJ45YV83X/CQYFEE00K) on the Tekton Slack and ask!
 
-Also, before and while you contribute, read the following topics:
-
-- [Content guidelines for Tekton documentation](doc-con-content.md)
-- [Formatting conventions for Tekton documentation](doc-con-formatting.md)
-- [Writing high quality documentation for Tekton](doc-con-writing.md)

content/en/doc-con-content.md → content/en/docs/Contribute/doc-con-content.md

 <!--
 ---
-linkTitle: "Content Guidelines"
+title: "Content guidelines"
+linkTitle: "Content guidelines"
 weight: 2
+description: >
+  Content guidelines for Tekton documentation
 ---
 -->
-## Content Guidelines for Tekton Documentation
 
 Follow these guidelines when planning and writing Tekton documentation. 
 
@@ -12,16 +14,37 @@ Follow these guidelines when planning and writing Tekton documentation.
 
 Each page in the Tekton documentation set must fall into one of the following categories:
 
-- **Concept** - explains a Tekton concept, such as what a `Task` is or how a `TaskRun` executes a `Task`.
-  It can be either high-level: "Understanding the flow of data in a `Pipeline`" or low-level:
-  "Understanding the `SmurfCapture` method in the Smurfcaptor API".
-- **Task** - contains procedures that explain how to do something in Tekton - for example, how to
-  create a `Task`.
-- **Tutorial** - guides you through a specific journey in order to familiarize you with multiple concepts
-  and tasks in one go. For example, a tutorial could explain how to set up a `Pipeline` that pulls source
-  code from GitHub and stores the outputs in the cloud. Tutorials are self-contained and goal-focused.
-- **Reference** - a collection of concepts that serves as an authoritative source of in-depth knowledge
-  about a specific area. A great example would be the Tekton API reference.
+-	**Tutorials** - These are introductory guides, focused on new users:
+	- Task-oriented
+	- Make sure it works: For Tekton, this means pick a runtime and stick with it
+		throughout the entire tutorial, so you can have reproducible steps that a
+		newcomer can copy-paste.
+	- Do not explain anything in detail, focus on doing. This is a common
+	  pitfall, trying to explain things too early.
+  - Do not provide more than one way of doing things. Pick the easiest path and
+    go with it. This is another common pitfall, trying to show everything you
+    can do in an introductory guide.
+	- Show results immediately.
+
+-	**How-to guides** - These are docs that explain how to complete a particular task:
+	- Goal oriented.
+	- Assumes some knowledge from the user, no need to start from scratch.
+	- Focus on the goal at hand.
+	- It’s fine to show several ways to achieve the goal, but there’s no need to
+		be comprehensive. (That’s what reference docs are for). 
+	- Provide a descriptive title.
+
+-	**Reference Guides** - These provide the technical details for everything
+	Tekton does. The most common example is the API reference docs:
+	- Be accurate
+	- Mirror the codebase when possible, so your reader knows what to expect.
+
+-	**Explanations** - Conceptual information:
+	- Descriptive content, explain how things work
+	- Do not include steps here
+
+You can find an in-depth discussion about this documentation framework in the
+[Grand Unified Theory of Documentation](https://diataxis.fr/).
 
 ## Structure
 
@@ -36,10 +59,11 @@ Follow these simple guidelines:
 
 ## Style and tone
 
-- **Always use active voice.** It's much easier to parse and more user-friendly (relatable) than passive. Passive voice
-  sounds stuffy and officious. It takes much more brain work to understand and causes the reader to zone out.
+- **Always use active voice.** It's much easier to parse and more user-friendly
+  (relatable) than passive. Passive voice sounds stuffy and officious. It takes
+  much more brain work to understand and causes the reader to zone out.
 
-    <table>
+<table>
   <tr>
    <td><strong>Do</strong>
    </td>
@@ -52,11 +76,12 @@ Follow these simple guidelines:
    <td>The files being installed are copied to the destination directory by the installer.
    </td>
   </tr>
-    </table>
+</table>
 
-- **Never use "should" or "might."** These words introduce uncertainty. We're either sure how our software works or we're not.
+- **Never use "should" or "might."** These words introduce uncertainty. We're
+  either sure how our software works or we're not.
 
-    <table>
+<table>
   <tr>
    <td><strong>Do</strong>
    </td>
@@ -69,11 +94,13 @@ Follow these simple guidelines:
    <td>When you click <strong>Build</strong>, your build should start.
    </td>
   </tr>
-    </table>
+</table>
 
-- **Don't use future tense** unless no other way exists to convey the information. Future tense creates an unwanted deferral of the result, while the result of each step should be immediate. For example:
+- **Don't use future tense** unless no other way exists to convey the
+  information. Future tense creates an unwanted deferral of the result, while
+  the result of each step should be immediate. For example:
 
-    <table>
+<table>
   <tr>
    <td><strong>Do</strong>
    </td>
@@ -86,11 +113,12 @@ Follow these simple guidelines:
    <td>When you click <strong>Build</strong>, your build will start.
    </td>
   </tr>
-    </table>
+</table>
 
-- **Avoid repetition.** Repetition is a "mental stumbling block" that gets in the way of the reader's comprehension of the thought or topic. For example:
+- **Avoid repetition.** Repetition is a "mental stumbling block" that gets in
+  the way of the reader's comprehension of the thought or topic. For example:
 
-    <table>
+<table>
   <tr>
    <td><strong>Do</strong>
    </td>
@@ -103,11 +131,12 @@ Follow these simple guidelines:
    <td>Smurfcaptor supports single- and multi-Smurf capture events. Smurfcaptor also supports batch processing.
    </td>
   </tr>
-    </table>
+</table>
 
-- **Never use "we."** The reader will wonder whether they're part of the "we" or not. For example:
+- **Never use "we."** The reader will wonder whether they're part of the "we" or
+  not. For example:
 
-    <table>
+<table>
   <tr>
    <td><strong>Do</strong>
    </td>
@@ -120,12 +149,14 @@ Follow these simple guidelines:
    <td>In version 3.0 we added Smurf counting support.
    </td>
   </tr>
-    </table>
+</table>
 
-- **Never use "might" or "may."** "May" is often confused with "might" but they are not the same. "Might" introduces uncertainty
-  just like "should," while "may" implies the permission has been granted and not that an option or action is available to the user. For example:
+- **Never use "might" or "may."** "May" is often confused with "might" but they
+  are not the same. "Might" introduces uncertainty just like "should," while
+  "may" implies the permission has been granted and not that an option or action
+  is available to the user. For example:
 
-    <table>
+<table>
   <tr>
    <td><strong>Do</strong>
    </td>
@@ -144,7 +175,7 @@ Follow these simple guidelines:
    <td>You may choose high or low Smurf sensitivity.
    </td>
   </tr>
-    </table>
+</table>
 
 ## Calling out important things
 
@@ -183,5 +214,3 @@ Avoid the following:
 - **Copy-pasting large portions of existing documentation.** If you need to reuse a large piece of content,
     link it instead. Duplication inevitably leads to the two copies going out of sync and confusing readers.
 - **Vendor-specific links.** We don't want to imply any kind of endorsement.
-- **Links to external projects.** Do not link to projects outside of the Tekton repository.
-  Those projects might move or go away, leaving the link broken.

content/en/doc-con-formatting.md → content/en/docs/Contribute/doc-con-formatting.md

 <!--
 ---
-linkTitle: "Formatting Conventions"
-weight: 2
+title: "Formatting conventions"
+linkTitle: "Formatting conventions"
+weight: 3
+description: >
+  Formatting conventions for Tekton documentation
 ---
 -->
-# Formatting Conventions for Tekton Documentation
 
 Tekton documentation uses Markdown to format the content. See the[Markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
 to gain a basic understanding of Markdown conventions.
@@ -120,7 +122,7 @@ See the [Google Developer Style Guide entry on formatting lists](https://develop
 
   To force-catch a specific Smurf, run the following command:
 
-          ```
+  ```sh
   smurfcaptor -f <target-smurf>
   ```
   where `<target-smurf>` is the Smurf you want Smurfcaptor to catch.

content/en/doc-con-writing.md → content/en/docs/Contribute/doc-con-writing.md

 <!--
 ---
-linkTitle: "Writing Primer"
-weight: 2
+title: "Tips and tricks for good writing"
+linkTitle: "Tips and tricks for good writing"
+weight: 3
+description:
+  Tips and tricks to write high quality documentation
 ---
 -->
-# Writing High Quality Documentation for Tekton
 
 “I hate writing!” is a line heard all too often. Documenting a feature can be an intimidating task. 
 
@@ -98,4 +100,4 @@ the document.
 ## How can I learn more?
 
 Take a look at the [Google Developer Style Guide](https://developers.google.com/style/). It covers
-style, tone, grammar, and punctuation. Also, ask @sergetron for reading recommendations!
+style, tone, grammar, and punctuation.

content/en/docs/Contribute/run-locally.md

+<!--
+---
+title: "Run the site locally"
+linkTitle: "Run the site locally"
+weight: 1
+description: > 
+   Run the Tekton documentation site locally
+---
+-->
+
+## Running in a Docker container
+
+### Prerequisites
+
+Install [Docker Compose](https://docs.docker.com/compose/install/).
+
+### Setup
+
+1. Build the Docker image
+
+   ```bash
+   docker-compose build
+
+   ```
+
+1. Run the built image
+
+   ```bash
+   docker-compose up
+   ```
+
+1. Verify that the website is working
+
+   Open your web browser and type `http://localhost:8888` in the navigation bar.
+   This opens a local instance of the website, you can now make changes in the
+   documentation and those changes will immediately show up in the browser after
+   you save.
+
+To remove the produced images run:
+
+```bash
+docker-compose rm
+```
+
+## Running Natively
+
+### Prerequisites
+
+* [python3](https://www.python.org/downloads/) 
+* [hugo (EXTENDED VERSION)](https://github.com/gohugoio/hugo/releases)
+* [pip](https://pip.pypa.io/en/stable/installing/)
+* [git 1.8.5 or later](https://github.com/git/git/releases)
+* [npm v6.14.5](https://nodejs.org/en/)
+* [node v14.3.0](https://nodejs.org/en/)
+* [netlify cli](https://cli.netlify.com/getting-started)
+* [netlify account](https://app.netlify.com/)
+
+### Setup
+
+1. Clone the repository
+
+   ```bash
+   git clone https://github.com/tektoncd/website && cd website
+   ```
+
+1. Install the required node modules
+
+   ```bash
+   npm install
+   ```
+
+1. Install the dependencies for the [sync script](https://github.com/tektoncd/website/blob/master/sync/README.md)
+
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate    
+   pip3 install -r requirements.txt
+
+   ```
+
+1. Run the sync script
+
+   ```bash
+   ./sync/sync.py
+   ```
+
+1. Serve the website locally
+
+   ```bash
+   netlify dev
+   ```
+
+1. Verify that the website is working
+
+   Open your web browser and type `http://localhost:8888` in the navigation bar.
+   This opens a local instance of the website, you can now make changes in the
+   documentation and those changes will immediately show up in the browser after
+   you save.
+
+The `sync.py` script clones the required repositories to a local cache folder, by default `sync/.cache`.
+You can modify content and create commits in your local cache to test changes to the original docs.
+
+To force and update of the local cache, use `./sync/sync.py --update-cache`.
+

roadmap.md

-# Tekton Website Roadmap
+# Tekton Website 2022 Roadmap
 
 We are continually working to improve the user experience on the Tekton website.
 
-The following is a list of projects we are working on or planning to work on in the near future:
+The following is a (non-comprehensive) list of things we are working on or
+planning to work on in 2022:
 
-## Tutorial improvements
+- Use a single framework for all the introductory tutorials. Probably
+  [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/), which is available
+  for Windows, Mac, and Linux.
 
-We are working on revamping and updating our tutorials to make ramping up on Tekton and its components easier for new users. We want to make our tutorials easier to understand and more relatable to real life scenarios.
+- Update Katakoda tutorials or look for a feasible alternative and try to keep
+  the content close to what the tutorials cover.
 
-## Announcements
+- Reorder the main navigation panel to a structure that follows a logical order
+  instead of the current one.
 
-We're working to add support for announcements using the blog feature of the Docsy template. A blog post will be published for each release of a Tekton component describing the new features, changes, and bug fixes in that release. See [issue 218](https://github.com/tektoncd/website/issues/218).
+- Update link in [tekton.dev](https://tekton.dev) to take users to the "Getting
+  started" section, since the interactive tutorial are currently out of date.
 
-## Community page
+- Work on a solution to communicate the status: alpha, beta, stable, or
+  deprecated; of the components.
+
+- Update the website theme to the latest version of Docsy.
+
+- Come up with a solution to avoid content drifting as the components are
+  updated. Try to keep the how-to always up-to-date.
+
+
+## Updates to documentation structure
+
+This structure is intended to make the documentation more friendly for newcomers
+without disrupting the current content too much. We hope to reorganize the
+current documentation and create new content, the site will look close to the
+following (see also the [content
+guidelines](https://tekton.dev/docs/contribute/doc-con-content/) to learn what
+to expect from each type of document):
+
+- **Installation** (*tutorials*) - Basic installation steps for several
+  components, to be used as a prerequisite for getting started. Link to the
+  installation readmes for further information about setup.
+
+  - Pipelines
+  - Triggers
+  - CLI
+  - Operator
+
+- **Getting Started** (*tutorials*) - Guides for newcomers. Mostly "Hello World"
+  tutorials for every component.
+  
+  - Getting started with Tasks
+  - Getting started with Pipelines
+  - Getting started with Triggers
+  - Getting started with Tekton CLI
+
+- **Concepts** (*explanations*) - Details about how things work. Rationale
+  behind implementation decisions and anything else worth explaining.
 
-Create a "Community" page using the community page feature of the Docsy template. The page will display content from the [tektoncd/community](https://github.com/tektoncd/community) repo. See [issue 217](https://github.com/tektoncd/website/issues/217).
+  - Tekton Overview
+  - Pipelines
+  - Triggers
 
-## "Getting Started" guides for Tekton
+- **How-to guides** (*how-to*) - Real-life examples.
+
+  - Build and deploy a container with Tekton.
+  - Setup Tekton Triggers with GitHub
+  - Pushing container containers images to a Registry.
+  - Using (cloud provider) storage with Tekton.
+  - Cloning private repositories.
+  - (New ideas and contributions are welcome)
+
+- **Reference** (*reference*) - Detailed documentation about every component.
+  Mostly the current documents.
+
+  - Pipelines
+  - Triggers
+  - CLI
+  - Operator
+  - Dashboard
+  - Result
+  - Chains
+  - API docs (organize APIs for every project)
+
+- **Contribute to documentation** (*how-to*)
+
+  - Run the site locally
+  - Content guidelines
+  - Formatting conventions
+  - Tips and tricks for good writing
+
+
+## Announcements
+
+We're working to add support for announcements using the blog feature of the
+Docsy template. A blog post will be published for each release of a Tekton
+component describing the new features, changes, and bug fixes in that release.
+See [issue 218](https://github.com/tektoncd/website/issues/218).
+
+## Community page
 
-We are working on "Getting Started" guides for Tekton that will describe how to deploy, configure, and integrate Tekton Pipelines with other Tekton components to create a fully working build environment.
+Create a "Community" page using the community page feature of the Docsy
+template. The page will display content from the
+[tektoncd/community](https://github.com/tektoncd/community) repo. See [issue
+217](https://github.com/tektoncd/website/issues/217).
 
 ## Versioned URLs for the /docs folder
 
-Right now, the website provides an unversioned URL to current release docs in the /docs folder and versioned URLs to previous release docs in the /vault folder. However, any links to docs for a given release pointing to the /docs folder become irrelevant as soon as a new release is out. To remedy this, we want to implement versioned URLs for the /docs folder as well.
+Right now, the website provides an unversioned URL to current release docs in
+the /docs folder and versioned URLs to previous release docs in the /vault
+folder. However, any links to docs for a given release pointing to the /docs
+folder become irrelevant as soon as a new release is out. To remedy this, we
+want to implement versioned URLs for the /docs folder as well.