From 857ecae05a2731afb969bbb3727ad10707f2c020 Mon Sep 17 00:00:00 2001 From: Geri Ochoa Date: Tue, 1 Feb 2022 00:48:03 -0500 Subject: [PATCH] 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-content.md | 187 --------------- content/en/doc-con-formatting.md | 178 --------------- .../Contribute/_index.md} | 40 +--- content/en/docs/Contribute/doc-con-content.md | 216 ++++++++++++++++++ .../en/docs/Contribute/doc-con-formatting.md | 180 +++++++++++++++ .../{ => docs/Contribute}/doc-con-writing.md | 10 +- content/en/docs/Contribute/run-locally.md | 104 +++++++++ roadmap.md | 109 ++++++++- 8 files changed, 616 insertions(+), 408 deletions(-) delete mode 100644 content/en/doc-con-content.md delete mode 100644 content/en/doc-con-formatting.md rename content/en/{doc-con-main.md => docs/Contribute/_index.md} (68%) create mode 100644 content/en/docs/Contribute/doc-con-content.md create mode 100644 content/en/docs/Contribute/doc-con-formatting.md rename content/en/{ => docs/Contribute}/doc-con-writing.md (93%) create mode 100644 content/en/docs/Contribute/run-locally.md diff --git a/content/en/doc-con-content.md b/content/en/doc-con-content.md deleted file mode 100644 index ff4e9b96..00000000 --- a/content/en/doc-con-content.md +++ /dev/null @@ -1,187 +0,0 @@ - -## Content Guidelines for Tekton Documentation - -Follow these guidelines when planning and writing Tekton documentation. - -## Types of content - -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. - -## Structure - -We want our documentation to be easily digestible, so make sure your writing is clear and concise. -Follow these simple guidelines: - -* Break up long thoughts into multiple sentences. -* Break up longer documents into logical sections. -* Use paragraphs to separate thoughts and ideas. -* Ensure paragraphs flow into one another - that is, they are logically connected. -* Use headings and subheadings to indicate topics and sub-topics. - -## 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. - - - - - - - - - - -
Do - Don't -
The installer copies the files to the destination directory. - The files being installed are copied to the destination directory by the installer. -
- -- **Never use "should" or "might."** These words introduce uncertainty. We're either sure how our software works or we're not. - - - - - - - - - - -
Do - Don't -
Click Build to start your build. - When you click Build, your build should start. -
- -- **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: - - - - - - - - - - -
Do - Don't -
Click Build to start your build. - When you click Build, your build will start. -
- -- **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: - - - - - - - - - - -
Do - Don't -
Smurfcaptor supports single- and multi-Smurf capture events, including batch processing. - Smurfcaptor supports single- and multi-Smurf capture events. Smurfcaptor also supports batch processing. -
- -- **Never use "we."** The reader will wonder whether they're part of the "we" or not. For example: - - - - - - - - - - -
Do - Don't -
Version 3.0 adds support for Smurf counting. - In version 3.0 we added Smurf counting support. -
- -- **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: - - - - - - - - - - - - - - -
Do - Don't -
The build starts when you click Build. - The build might start when you click Build. -
You can choose either high or low Smurf sensitivity. - You may choose high or low Smurf sensitivity. -
- -## Calling out important things - -To call out something of particular importance, use the three severity levels of callouts: note, caution, and warning. - - - - - - - - - - - - - - - - - -
Callout Type - Example -
Note calls the reader's attention to something important. - Note: It is best to capture Smurfs in batches, as processing a large number of Smurfs at once can result in long wait times. -
Caution indicates something that may cost the reader additional time and work if not followed. - Caution: Papa Smurf is a highly skilled mage. To maximize your Smurf yields, avoid capturing him along with other Smurfs. -
Warning warns the reader of a potential catastrophic failure. - Warning: Looking directly into the Basilisk's eyes turns you instantly to stone. -
- -## Things to avoid - -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. diff --git a/content/en/doc-con-formatting.md b/content/en/doc-con-formatting.md deleted file mode 100644 index 3decc9f5..00000000 --- a/content/en/doc-con-formatting.md +++ /dev/null @@ -1,178 +0,0 @@ - -# 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. - -## Lists - -The key point of lists is that they present information in quickly scannable form, -and to accomplish that they must be homogeneous. If the items in the list do not -look and read the same, the reader will stumble on them. Follow these guidelines: - -- Keep the length and language of your list items as homogeneous as possible. - If, for example, most of your list items are single words or short fragments, try - to rewrite the outliers to read like the rest. - -- Capitalize the first word of each item. - -- Punctuate the ends of **all** items in the list as follows: - - - If your list items are single words or short fragments without verbs, - **do not put a period** at the end of each item. - - - If most of your list items are complete sentences or fragments that contain verbs, - **put a period** at the end of each item. - -See the [Google Developer Style Guide entry on formatting lists](https://developers.google.com/style/lists) for more detail. - -## User interface elements - -- Use **bold** to indicate anything that's clickable, such as buttons or menu items. - - - - - - - - - - -
- Do - Don't -
Start your build by clicking Build. - Click on the build button to start your build. -
- -- Use the exact label given to the UI element, screen, or page. - - - - - - - - - - -
Do - Don't -
Choose your Smurfs by clicking Select Smurfs. - Click select to choose your Smurfs. -
- -- Use "quotes" to denote the name of a non-clickable elements, such as a menu or a page. - - - - - - - - - - -
Do - Don't -
Click Next to advance to the "Set Up Billing" page. - Click Next to open the billing setup page. -
- -## Commands and code - -- Format these as code and indicate what they are: - - - API objects - - Commands - - Names of files and directories - - For example: - - - - - - - - - - - - - - -
Do - Don't -
Define a new TaskRun instance. - Define a new taskrun. -
Run the smurfcaptor command. - Run smurfcaptor. -
- -- Use angle brackets for placeholders, such as variables, and tell the reader what the placeholders represent. For example: - - To force-catch a specific Smurf, run the following command: - - ``` - smurfcaptor -f - ``` - where `` is the Smurf you want Smurfcaptor to catch. - - - When the operation completes, Smurfcaptor displays the result. - -- Use informative variable names and format them using camelCase. For example: - - - - - - - - - - -
Do - Don't -
targetSmurf - tarsmu -
- -- Remove trailing spaces. Some markdown objects, such as lists, require a specific number of spaces, - and often, the absence of spaces in specific places, in order to render properly on the website. - They can also cause unnecessary lint errors. - -## Links - -- **Never use "here" or "this" as a link anchor.** Use either the exact title of the document being - linked, or descriptive, in-context phrase and a brief description of the link target. This enables - more meaningful results when searching the documentation set, and is more informative to the reader. - For example: - - - - - - - - - - - - - - -
Do - Don't -
For more information, see Installing Smurfcaptor. - For more information, go here. -
See the Tekton website for tutorials that cover Smurfcaptor integration. - Go to this site for tutorials. -
diff --git a/content/en/doc-con-main.md b/content/en/docs/Contribute/_index.md similarity index 68% rename from content/en/doc-con-main.md rename to content/en/docs/Contribute/_index.md index d4d2778f..05d0fb70 100644 --- a/content/en/doc-con-main.md +++ b/content/en/docs/Contribute/_index.md @@ -1,35 +1,22 @@ -# 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) diff --git a/content/en/docs/Contribute/doc-con-content.md b/content/en/docs/Contribute/doc-con-content.md new file mode 100644 index 00000000..3f59a838 --- /dev/null +++ b/content/en/docs/Contribute/doc-con-content.md @@ -0,0 +1,216 @@ + + +Follow these guidelines when planning and writing Tekton documentation. + +## Types of content + +Each page in the Tekton documentation set must fall into one of the following categories: + +- **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 + +We want our documentation to be easily digestible, so make sure your writing is clear and concise. +Follow these simple guidelines: + +* Break up long thoughts into multiple sentences. +* Break up longer documents into logical sections. +* Use paragraphs to separate thoughts and ideas. +* Ensure paragraphs flow into one another - that is, they are logically connected. +* Use headings and subheadings to indicate topics and sub-topics. + +## 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. + + + + + + + + + + +
Do + Don't +
The installer copies the files to the destination directory. + The files being installed are copied to the destination directory by the installer. +
+ +- **Never use "should" or "might."** These words introduce uncertainty. We're + either sure how our software works or we're not. + + + + + + + + + + +
Do + Don't +
Click Build to start your build. + When you click Build, your build should start. +
+ +- **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: + + + + + + + + + + +
Do + Don't +
Click Build to start your build. + When you click Build, your build will start. +
+ +- **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: + + + + + + + + + + +
Do + Don't +
Smurfcaptor supports single- and multi-Smurf capture events, including batch processing. + Smurfcaptor supports single- and multi-Smurf capture events. Smurfcaptor also supports batch processing. +
+ +- **Never use "we."** The reader will wonder whether they're part of the "we" or + not. For example: + + + + + + + + + + +
Do + Don't +
Version 3.0 adds support for Smurf counting. + In version 3.0 we added Smurf counting support. +
+ +- **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: + + + + + + + + + + + + + + +
Do + Don't +
The build starts when you click Build. + The build might start when you click Build. +
You can choose either high or low Smurf sensitivity. + You may choose high or low Smurf sensitivity. +
+ +## Calling out important things + +To call out something of particular importance, use the three severity levels of callouts: note, caution, and warning. + + + + + + + + + + + + + + + + + +
Callout Type + Example +
Note calls the reader's attention to something important. + Note: It is best to capture Smurfs in batches, as processing a large number of Smurfs at once can result in long wait times. +
Caution indicates something that may cost the reader additional time and work if not followed. + Caution: Papa Smurf is a highly skilled mage. To maximize your Smurf yields, avoid capturing him along with other Smurfs. +
Warning warns the reader of a potential catastrophic failure. + Warning: Looking directly into the Basilisk's eyes turns you instantly to stone. +
+ +## Things to avoid + +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. diff --git a/content/en/docs/Contribute/doc-con-formatting.md b/content/en/docs/Contribute/doc-con-formatting.md new file mode 100644 index 00000000..0f02c8b4 --- /dev/null +++ b/content/en/docs/Contribute/doc-con-formatting.md @@ -0,0 +1,180 @@ + + +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. + +## Lists + +The key point of lists is that they present information in quickly scannable form, +and to accomplish that they must be homogeneous. If the items in the list do not +look and read the same, the reader will stumble on them. Follow these guidelines: + +- Keep the length and language of your list items as homogeneous as possible. + If, for example, most of your list items are single words or short fragments, try + to rewrite the outliers to read like the rest. + +- Capitalize the first word of each item. + +- Punctuate the ends of **all** items in the list as follows: + + - If your list items are single words or short fragments without verbs, + **do not put a period** at the end of each item. + + - If most of your list items are complete sentences or fragments that contain verbs, + **put a period** at the end of each item. + +See the [Google Developer Style Guide entry on formatting lists](https://developers.google.com/style/lists) for more detail. + +## User interface elements + +- Use **bold** to indicate anything that's clickable, such as buttons or menu items. + + + + + + + + + + +
+ Do + Don't +
Start your build by clicking Build. + Click on the build button to start your build. +
+ +- Use the exact label given to the UI element, screen, or page. + + + + + + + + + + +
Do + Don't +
Choose your Smurfs by clicking Select Smurfs. + Click select to choose your Smurfs. +
+ +- Use "quotes" to denote the name of a non-clickable elements, such as a menu or a page. + + + + + + + + + + +
Do + Don't +
Click Next to advance to the "Set Up Billing" page. + Click Next to open the billing setup page. +
+ +## Commands and code + +- Format these as code and indicate what they are: + + - API objects + - Commands + - Names of files and directories + + For example: + + + + + + + + + + + + + + +
Do + Don't +
Define a new TaskRun instance. + Define a new taskrun. +
Run the smurfcaptor command. + Run smurfcaptor. +
+ +- Use angle brackets for placeholders, such as variables, and tell the reader what the placeholders represent. For example: + + To force-catch a specific Smurf, run the following command: + + ```sh + smurfcaptor -f + ``` + where `` is the Smurf you want Smurfcaptor to catch. + + + When the operation completes, Smurfcaptor displays the result. + +- Use informative variable names and format them using camelCase. For example: + + + + + + + + + + +
Do + Don't +
targetSmurf + tarsmu +
+ +- Remove trailing spaces. Some markdown objects, such as lists, require a specific number of spaces, + and often, the absence of spaces in specific places, in order to render properly on the website. + They can also cause unnecessary lint errors. + +## Links + +- **Never use "here" or "this" as a link anchor.** Use either the exact title of the document being + linked, or descriptive, in-context phrase and a brief description of the link target. This enables + more meaningful results when searching the documentation set, and is more informative to the reader. + For example: + + + + + + + + + + + + + + +
Do + Don't +
For more information, see Installing Smurfcaptor. + For more information, go here. +
See the Tekton website for tutorials that cover Smurfcaptor integration. + Go to this site for tutorials. +
diff --git a/content/en/doc-con-writing.md b/content/en/docs/Contribute/doc-con-writing.md similarity index 93% rename from content/en/doc-con-writing.md rename to content/en/docs/Contribute/doc-con-writing.md index 1027e7e0..dfa99032 100644 --- a/content/en/doc-con-writing.md +++ b/content/en/docs/Contribute/doc-con-writing.md @@ -1,10 +1,12 @@ -# 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. diff --git a/content/en/docs/Contribute/run-locally.md b/content/en/docs/Contribute/run-locally.md new file mode 100644 index 00000000..2fb431b9 --- /dev/null +++ b/content/en/docs/Contribute/run-locally.md @@ -0,0 +1,104 @@ + + +## 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`. + diff --git a/roadmap.md b/roadmap.md index 0ab6e83e..1f0ff850 100644 --- a/roadmap.md +++ b/roadmap.md @@ -1,25 +1,112 @@ -# 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.