Tekton – Contribute

Docs: Content guidelines

Mon, 01 Jan 0001 00:00:00 +0000

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.

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. Don’t use more than 3 subheading levels.

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.

Docs: Contribute Code

Mon, 01 Jan 0001 00:00:00 +0000

If you would like to contribute code to Tekton, we’d love your help! Tekton is an open source project and we welcome contributions from everyone.

Getting started

Check out the Tekton Community page for an overview of how to get involved. The community page covers:

Contribution standards - code of conduct, design principles, and coding standards.
Contribution process - how to find something to work on, propose features, submit pull requests, and climb the contributor ladder.
Community spaces - Slack, mailing lists, working groups, and meetings.

Finding something to work on

Browse the GitHub repositories under the tektoncd organization. Look for issues labeled good first issue or help wanted to get started.

You can also check the community process documentation for more guidance.

Key resources

Resource	Description
Contributor ladder	How to grow your role in the project
Design principles	Core design values for Tekton
Code standards	Coding conventions and standards
Commit standards	Commit message conventions
Pull request reviews	How the review process works
Propose new features	TEP process for feature proposals

I need help!

If you’re not sure where to start, join the Tekton Slack and ask in the relevant project channel. You can also reach out on the tekton-dev mailing list.

Docs: Formatting conventions

Mon, 01 Jan 0001 00:00:00 +0000

Tekton documentation uses Markdown to format the content. See the CommonMark tutorial to learn the basics.

Markdown formatting conventions:

Lists
- Capitalize the first word for each item.
- Don’t put a period at the end of each item in lists containing only nouns or single-word items.
- Use sentence punctuation in any other case.
Code Format
- Use code formatting when referencing API objects, commands, files and directories.
- Use angle brackets for placeholders such as variables. For example:
```
kubectl apply -f <pipeline-file>
```
Markdown files
- Hard-wrap the file lines so they are not longer than 80 characters.
- Use reference-style links if the URL is too long. There’s no specific URL length, use your best judgment to keep markdown files readable.

Embed code samples

You can import code from external files. To do this, use the readfile shortcode with the code and lang options. For example, the following code embeds the file samples/task.yaml:

{{< readfile file="samples/task.yaml" code="true" lang="yaml" >}}

This is rendered as:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: hello
spec:
  steps:
    - name: echo
      image: alpine
      script: |
        #!/bin/sh
        echo "Hello World"

You can also embed code samples in tabs using the tabpane shortcode. For example, the following code embeds samples/pipeline1.yaml and samples/pipeline2.yaml in different tabs:

{{< tabs >}}
{{< tab "v1beta1" >}}
{{< readfile file="samples/pipeline1.yaml" code="true" lang="yaml" >}}
{{< /tab >}}

{{< tab "v1" >}}
{{< readfile file="samples/pipeline2.yaml" code="true" lang="yaml" >}}
{{< /tab >}}
{{< /tabs >}}

Rendered as:

v1beta1
v1

apiVersion: tekton.dev/v1beta1
kind: TaskRun
spec:
  taskRef:
    name: example-task
    bundle: python:3-alpine

apiVersion: tekton.dev/v1
kind: TaskRun
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: python:3-alpine
    - name: name
      value: taskName
    - name: kind
      value: Task

Warning

The path parameter don’t support relative paths to parent directories. For example, path="../sample.yaml" does not work.

Docs: Platform-specific documentation

Mon, 01 Jan 0001 00:00:00 +0000

Important: Documentation contributions to this website must be licensed under the Creative Commons Attribution 4.0 License, and the code samples must be licensed under the Apache 2.0 License.

Guides to use Tekton with third-party services.

Before you begin

To preview your documentation, check the guide on how to run this site locally.

Contributing documentation for the first time

Before you contribute, we strongly recommend that you join the TektonCD Slack and the Tekton TW working group.

Create a new folder under content/en/vendor/ with a descriptive vendor name. Lower case, use dashes to separate words.
Write the documentation following the content guidelines and formatting conventions.

Surface your documentation in existing guides

Create a new file under content/en/vendor/<your-vendor>/ with a descriptive name.
Write the content as if it was part of the guide you want it to appear in. Keep in mind the style and tone of the parent document. Do not use first level headers.

In the relevant guide, use the tabs and readfile shortcodes to display your content alongside existing information. For example, to add platform-specific authentication steps to the “Authentication” section of an existing guide:

## Authentication

{{< tabs >}}

{{< tab "Default" >}}
  Default authentication process:

  1. Step 1
  2. Step 2
{{< /tab >}}

{{< tab "My cloud provider" >}}
{{< readfile file="/vendor/my-vendor/my-service-auth.md" >}}
{{< /tab >}}

{{< /tabs >}}

If it’s not already there, add the vendor disclaimer at the top of the document, below the front matter.
```
{{% pageinfo %}}
{{% readfile "/vendor/disclaimer.md" %}}
{{% /pageinfo %}}
```

Publishing new guide

If you want to publish a standalone document instead of contributing to an existing one:

Write your new document and save it under content/en/vendor/<your-vendor>/. Do not use a first level header for the title. You are going to set the title of the document in a subsequent step.
Determine the correct place show the document, that would usually be in one one of the following sections:
- Installation
- Getting Started
- How-to Guides
See the content guidelines for more information.
In the folder corresponding to the section you selected, create a new file with a descriptive name. Add a hugo front matter in YAML format. For example, suppose you are adding a new installation guide, create the file content/en/docs/Installation/my-vendor-install.md with the following front matter:
```
---
title: Install Tekton on my cloud service
linkTitle: Install Tekton on my cloud service
weight: 3
description: >
    Installation guide to run Tekton on my cloud service.
---
```
Keep in mind that the weight parameter determines the order in the left navigation pane. Lower numbers appears earlier in the list, documents with the same weight are ordered alphabetically.

Add the vendor disclaimer at the top of the document, below the front matter.

{{% pageinfo %}}
{{% readfile "/vendor/disclaimer.md" %}}
{{% /pageinfo %}}

Import your file with the readfile shortcode. The final markdown file looks like this:

 ---
 title: Install Tekton on my cloud service
 linkTitle: Install Tekton on my cloud service
 weight: 3
 description: >
   Installation guide to run Tekton on my cloud service.
 ---

 {{% pageinfo %}}
 {{% readfile "/vendor/disclaimer.md" %}}
 {{% /pageinfo %}}

 {{% readfile "/vendor/my-vendor/installation.md" %}}

Caveats

Because Docsy, the platform Tekton docs are built on, rebuilds files when their content changes, it will not pick up the changes in your included files unless you make a change on the parent file. You can make a small change, like increasing a dummy counter, while writing content to trigger rebuilding the parent file.
Documentation using this approach is meant to be read on the website. Reading the source files on GitHub will not be the best experience.

Own your docs

If you are contributing documentation to show how Tekton works with a particular platform, we encourage you to own your documentation.

Ensure freshness and accuracy.
Review reported user issues regarding your documentation.
Review Pull Requests to your docs.

Docs: Run the site locally

Mon, 01 Jan 0001 00:00:00 +0000

Running in a Docker container

Install Docker Compose.
Build the Docker image:
```
docker-compose build
```
Run the built image:
```
docker-compose up
```
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.
Hit Ctrl + C to stop the container.

To remove the produced images run:

docker-compose rm

Running Natively

Prerequisites

Setup

Clone the repository

git clone https://github.com/tektoncd/website && cd website

Install the required node modules
```
npm install
```

Install the dependencies for the sync script

python3 -m venv .venv
source .venv/bin/activate    
pip3 install -r requirements.txt

Run the sync script
```
./sync/sync.py
```
Serve the website locally
```
netlify dev
```
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.

Docs: Tips and tricks for good writing

Mon, 01 Jan 0001 00:00:00 +0000

“I hate writing!” is a line heard all too often. Documenting a feature can be an intimidating task.

The most common questions that come up when writing a document are:

“Where do I start?”
“What do I say?”
“How do I know when I’m done?”
“Who can I ask for help?”
“Where can I find writing resources?”

These and many other questions can form mental barriers that discourage from contributing to documentation. When we remove or lower these barriers, writing can become an enjoyable, satisfying activity.

I hate writing!

That’s fine. Professional writers do, too. We’re just better at hiding it! The first thing to remember is that writing is an iterative process. Professional writers never produce the perfect document on their first try.

Instead, we start with an SFD (Shoddy First Draft), and then edit, edit, edit. The goal is not to write a perfect document, but to write one that is good enough to convey the information in an approachable way. This removes the pressure of writing a polished piece and instead lets us focus on conveying the correct information in the right order and proportion.

Write an SFD and brainstorm it with others - it really works!

Where do I start?

Begin by asking yourself, “Who is my audience?” Engineers? Less technical readers, such as management? Aliens? Once you know your audience, you’ll know how much detail to include, the tone to use, and who your reviewers will be.

Next, put yourself in your audience’s shoes and ask, “What do I, as this type of reader, need to know to use this thing I’m writing about?” Things that are obvious to you may not be obvious to an outsider. What tasks will the reader need to accomplish? What will they need to know to accomplish each task?

Write down headings representing each of those major points or areas. For example, “Installation,” “Configuration,” “Operation modes,” or “Command-line options.” These major things become the outline of your document.

What do I say?

Look at your outline. What does the reader need to know about each of those topics or areas of interest? For example, if you’re writing a procedure, you may also want to include prerequisites - that is, steps the reader must complete before starting the procedure. What are the possible scenarios when starting the procedure? What are the possible outcomes? Do the steps differ depending on the starting scenario and the desired outcome?

Write down some ideas or sub-topics for each key area. These become the mini table of contents for each section. Once you have those, your document outline is complete!

Flesh out one section at a time, keeping the level of detail appropriate to your audience. For example, if you’re writing a command-line reference, chances are the reader will be an advanced user who needs to understand the intricacies of each option, including allowed values, the default value, the behavior resulting from each value, and any exceptions and caveats.

On the other hand, if you’re documenting a specific feature, start by describing what it does, so that the reader has context, and describe how to use the feature afterwards. Put the “what” before the “how” and start simple, then introduce more detail as you go.

Active or passive voice?

Always use active voice. Active voice is much easier to parse and more relatable for the reader than passive voice. Passive voice sounds stuffy and officious; it reads like a boring legal document or that college textbook that made you fall asleep. It takes much more brain work to understand and causes the reader to zone out.

Consider the following:

“The files being installed are copied to the destination directory by the installer. The destination directory is created by the installer before the files are copied.”

And now read the same information in active voice:

“The installer creates the destination directory, then copies the files to it.”

Night and day, don’t you think?

How do I know when I’m done?

This is the hardest part. When do you stop writing?

Go over each section and ask yourself again, “would I know how to use this thing based solely on what’s written?” If so, send your document out for review. Tekton engineers and contributors will confirm the document’s technical accuracy, while a technical writer will polish the style, tone, and structure of the document.

How can I learn more?

Take a look at the Google Developer Style Guide. It covers style, tone, grammar, and punctuation.

Docs: Create a blog post

Mon, 01 Jan 0001 00:00:00 +0000

If you have an interesting, fun, or practical idea that you want to share with the world, you can write a blog post about it!

Blog posts don’t have to follow strict writing rules or styles. They are a good place for you to have fun talking about Tekton.

This is how:

Set up a local version of the website

Fork the documentation repository.

Clone the repository to your computer:

git clone https://github.com/<your-git-username>/website.git

Install Docker Compose, if it’s not already installed on your computer.

Change directory to the repository root and run the website server:

cd website
docker-compose up

And wait for the confirmation message to pop up:

┌─────────────────────────────────────────────────┐
│                                                 │
│   ◈ Server now ready on http://localhost:8888   │
│                                                 │
└─────────────────────────────────────────────────┘

Keep the server running while you write your post. Press Ctrl + C to stop it.

Open your browser and go to http://localhost:8888.

Draft your blog post

Create a folder under content/en/blog/<year>/ with a descriptive name. Lower case, use dashes to separate words.

Inside the newly created folder, create a file and add a front matter with the following format:

---
title: Title
likTitle: Title
date: <date, for example 2022-10-26>
author: "Author name"
description: >
    A heading sentence about your post
---

Save the file as index.md. As soon as you save it a new blog entry is now visible on your browser.
Below the front matter, write to your heart’s content. Every time you save, the server automatically builds the page and shows the changes.

If you need some inspiration, you can find examples on the website repository.

Open a PR for review

After you complete your blog post, open a Pull Request and wait for it to be reviewed.
Your blog post is now public and we are all excited to read it. Congratulations!