Flux – Documentation

Contributing: Docs from the ground up

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

Getting Started

If you already know Markdown, this is going to be straight-forward. For our docs we use markdown, and we get some additions through the Hugo static website generator and the Docsy theme, which we are going to line out here.

If you are unfamiliar with Markdown, please see https://guides.github.com/features/mastering-markdown/ (it’s a good cheat-sheet) or https://www.markdownguide.org/ if you are looking for something more substantial.

Starting at the top

Hugo allows you to specify metadata concerning an article at the top of the Markdown file, in a section called Front Matter. The Hugo website has a great article about it which explains all the relevant options.

For now, let’s take a look at a quick example which should explain the most relevant entries in Front Matter:

---
title: Using Flux on OpenShift
linkTitle: OpenShift
description: "How to bootstrap Flux on OpenShift."
weight: 20
---

## OpenShift Setup

Steps described in this document have been tested on OpenShift 4.6 only.

[...]

The top section between two lines of --- is the Front Matter section. Here we define a couple of entries which tell Hugo how to handle article:

title is the equivalent of the <h1> in a HTML document or # <title> in a Markdown article
linkTitle is the title to be used in the menu or navbar (usually you might want to pick something shorter and easier to spot)
description is shown in a list of documents - maybe the directory you are looking at has a _index.md document - this is where you would see the list of articles (and the short descriptions). Note you can write multi-line descriptions like so:
```
description: >
 more text here
 here is even more description
```
weight indicates where in the list of documents this is shown. It basically imposes an order on the articles in this directory.

Mixing Front Matter and top-level headings

Please note: Everything below the Front Matter entry is just the regular Markdown article as you would normally write it. Please note that headings start with ## <..>, as the title is defined in the Front Matter. Mixing Front Matter and # <..> headings will trip up Hugo and it might error out or not show the article.

Linking to other docs

You can easily link to other places using either

Absolute URLs, for linking off to external sites like https://github.com or https://k8s.io - you can use any of the Markdown notations for this, so
- <https://k8s.io> or
- [Kubernetes](https://k8s.io) will work.
Link to markdown files in other you can link to the .md file, or the resulting path. So if you are editing e.g. article1.md in content/en/flux/section-a and want to link to article2.md in the same directory you can use the following:
- [link](article2.md)
- [link](../article2/)
- [link](/flux/section-a/article2/)

Media, illustrations and more

If you want to illustrate the documentation and make things easier to read, there are lots of shortcodes either inherited through Hugo or through Docsy. Here is a list of our current favourites:

pageinfo for quick “banner type” info boxes
tabpane for pieces of text that go in different tabs
cardpane and card for adding cards and card panes
gist, youtube, tweet and more: lots of shortcodes we get from Hugo itself.

Code snippets

You can embed code snippets from a file. Please refer to https://www.docsy.dev/docs/adding-content/shortcodes/#include-code-files for hot to use the readfile shortcode.

Tabbed sections

You can create tabbed sections that contain both markdown and code snippets. Please refer to https://www.docsy.dev/docs/adding-content/shortcodes/#tabbed-panes for how to use the tabpane and tab shortcodes.

Gallery shortcodes

You can use gallery shortcodes to easily create and display photo galleries or image sliders within your posts or blogs. Please refer to https://github.com/mfg92/hugo-shortcode-gallery for how to use the hugo-shortcode-gallery tool.

Contributing: Proposing changes

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

Getting started

Familiarize yourself with the documentation repository and the website’s static site generator (Hugo).
Understand the process for opening a pull request and reviewing changes

Opening a pull request

To contribute new pages or improve existing pages, open a pull request (PR).

If your change is small, or you’re unfamiliar with git, read Changes using GitHub.

Changes using GitHub

If you’re less experienced with git workflows, here’s an easier method of opening a pull request.

Maintainer Warning

If you are a maintainer of the repo, the edit page button will not let you work off a fork, as you have write permission.

On the page you want to modify, select the pencil icon at the top right.
Make your changes in the GitHub markdown editor.
Below the editor, fill in the Propose file change form.

In the first field, give your commit message a title. In the second field provide a description

Warning
Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.
Select Propose file change.
Select Create pull request.
The Open a pull request screen appears. Fill in the form:
- The Subject field of the pull request defaults to the commit summary. You can change it if needed.
- The Body contains your extended commit message, if you have one, and some template text. Add the details the template text asks for, then delete the extra template text.
- Leave the Allow edits from maintainers checkbox selected.
PR descriptions are a great way to help reviewers understand your change. For more information, see Opening a PR.
Select Create pull request.

Addressing feedback in GitHub

Before merging a pull request, community members review and approve it.

If a reviewer asks you to make changes:

Go to the Files changed tab.
Select the pencil (edit) icon on any files changed by the pull request.
Make the changes requested.
Commit the changes.

Work from a local fork

If you’re more experienced with git, or if your changes are larger than a few lines, work from a local fork.

Fork the fluxcd/website repository

Navigate to the fluxcd/website repository.
Select Fork.
Navigate to the new website directory. Set the fluxcd/website repository as the upstream remote:
```
cd website

git remote add upstream https://github.com/fluxcd/website.git
```

Confirm your origin and upstream repositories:

git remote -v

Output is similar to:

origin git@github.com:<github_username>/website.git (fetch)
origin git@github.com:<github_username>/website.git (push)
upstream https://github.com/fluxcd/website.git (fetch)
upstream https://github.com/fluxcd/website.git (push)

Fetch commits from your fork’s origin/main and fluxcd/website’s upstream/main:
```
git fetch origin
git fetch upstream
```
This makes sure your local repository is up to date before you start making changes.

Create a new branch based on upstream/main:

git checkout -b <my_new_branch> upstream/main

Make your changes using a text editor.

At any time, use the git status command to see what files you’ve changed.

Commit your changes

When you are ready to submit a pull request, commit your changes.

In your local repository, check which files you need to commit:

git status

Output is similar to:

On branch <my_new_branch>
Your branch is up to date with 'origin/<my_new_branch>'.

Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: content/en/contribute/new-content/run-locally.md

no changes added to commit (use "git add" and/or "git commit -a")

Add the files listed under Changes not staged for commit to the commit:
```
git add <your_file_name>
```
Repeat this for each file.
After adding all the files, create a commit:
```
git commit -sm "Your commit message"
```
Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.
Push your local branch and its new commit to your remote fork:
```
git push origin <my_new_branch>
```

Open a pull request from your fork to fluxcd/website

In a web browser, go to the fluxcd/website repository.
Navigate to pull requests and select New pull request
Select compare across forks
From the head repository drop-down menu, select your fork.
From the compare drop-down menu, select your branch.
Select Create Pull Request.
Add a description for your pull request:
- Title (50 characters or less): Summarize the intent of the change.
- Description: Describe the change in more detail.
  - If there is a related GitHub issue, include Fixes #12345 or Closes #12345 in the description. GitHub’s automation closes the mentioned issue after merging the PR if used. If there are other related PRs, link those as well.
  - If you want advice on something specific, include any questions you’d like reviewers to think about in your description.
Select the Create pull request button.

Congratulations! Your pull request is available in Pull requests.

Addressing feedback locally

After making your changes, amend your previous commit:
```
git commit -as --amend
```
- -as: commits all changes and adds your signoff
- --amend: amends the previous commit, rather than creating a new one
Update your commit message if needed.
Use git push origin <my_new_branch> to push your changes and re-run the Netlify tests.

Changes from reviewers

Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits.

Fetch commits from your remote fork and rebase your working branch:
```
git fetch origin
git rebase origin/<your-branch-name>
```

After rebasing, force-push new changes to your fork:

git push --force-with-lease origin <your-branch-name>

Adding DCO on commits retroactively

Open an interactive rebase session

git rebase --signoff HEAD~<number of commits in your pr>

Verify you have signed the commits
```
git log
```
Force push
```
git push -f origin branchname
```

Merge conflicts and rebasing

For more information, see Git Branching - Basic Branching and Merging, Advanced Merging, or ask in the #sig-docs Slack channel for help.

If another contributor commits changes to the same file in another PR, it can create a merge conflict. You must resolve all merge conflicts in your PR.

Update your fork and rebase your local branch:

git fetch origin
git rebase origin/<your-branch-name>

Then force-push the changes to your fork:

git push --force-with-lease origin <your-branch-name>

Fetch changes from fluxcd/website’s upstream/main and rebase your branch:
```
git fetch upstream
git rebase upstream/main
```
Inspect the results of the rebase:
```
git status
```
This results in a number of files marked as conflicted.
Open each conflicted file and look for the conflict markers: >>>, <<<, and ===. Resolve the conflict and delete the conflict marker.

For more information, see How conflicts are presented.
Add the files to the changeset:
```
git add <filename>
```
Continue the rebase:
```
git rebase --continue
```
Repeat steps 2 to 5 as needed.

After applying all commits, the git status command shows that the rebase is complete.
Force-push the branch to your fork:
```
git push --force-with-lease origin <your-branch-name>
```
The pull request no longer shows any conflicts.

Contributing: Documentation Style Guide

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

Documentation formatting standards

This page gives writing style guidelines for the Flux documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Note: Flux documentation uses Goldmark Markdown Renderer with some adjustments along with a few Hugo Shortcodes to support glossary entries, tabs, and representing feature state.

Use upper camel case for API objects

When you refer specifically to interacting with an API object, use UpperCamelCase, also known as Pascal case.

When you are generally discussing an API object, use sentence-style capitalization.

You may use the word “resource”, “API”, or “object” to clarify a Flux resource type in a sentence.

Don’t split an API object name into separate words. For example, use HelmRelease, not Helm Release.

The following examples focus on capitalization. For more information about formatting API object names, review the related guidance on Code Style.

Do	Don’t
The GitRepository resource is responsible for …	The Git Repository resource is responsible for …

Use angle brackets for placeholders

Use angle brackets (<>) for placeholders. Tell the reader what a placeholder represents, for example

Reconcile a kustomization :

flux reconcile kustomization <name> --with-source

Use bold for user interface elements

Do	Don’t
Click Fork.	Click “Fork”.
Select Other.	Select “Other”.

Use italics to define or introduce new terms

Do	Don’t
A Reconciliation is …	A “Reconciliation” is …

Use code style for filenames, directories, and paths

Do	Don’t
Open the `envars.yaml` file.	Open the envars.yaml file.
Go to the `/docs/tutorials` directory.	Go to the /docs/tutorials directory.
Open the `/_data/concepts.yaml` file.	Open the /_data/concepts.yaml file.

Use the international standard for punctuation inside quotes

Do	Don’t
events are recorded with an associated “stage”.	events are recorded with an associated “stage.”
The copy is called a “fork”.	The copy is called a “fork.”

Inline Code Formatting

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).

Use code style for inline code, commands, and API objects

Do	Don’t
The `flux bootstrap` command creates a `Pod`.	The “flux bootstrap” command creates a pod.
The Helm controller manages `HelmRelease` objects…	The Helm controller manages HelmRelease objects…
A `Kustomization` represents …	A Kustomization represents …
Enclose code samples with triple backticks. (```)	Enclose code samples with any other syntax.
Use single backticks to enclose inline code. For example, `var example = true`.	Use two asterisks (``) or an underscore (`_`) to enclose inline code. For example, var example = true**.
Use triple backticks before and after a multi-line block of code for fenced code blocks.	Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.
Use meaningful variable names that have a context.	Use variable names such as ‘foo’,‘bar’, and ‘baz’ that are not meaningful and lack context.
Remove trailing spaces in the code.	Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.

Use code style for object field names

Do	Don’t
Set the value of the `interval` field in the configuration file.	Set the value of the “interval” field in the configuration file.
The value of the `chart` field is an HelmChartTemplate object.	The value of the “chart” field is an HelmChartTemplate object.

Use code style for Flux command-line tool and component names

Do	Don’t
The Source controller preserves node stability.	The `source-controller` preserves node stability.
The `flux` tool handles installation.	The flux tool handles installation.
Run the command to get Kustomizations with the name, `flux get kustomization <name>`.	Run the command to get Kustomizations with the name, flux get kustomization <name>.

Starting a sentence with a component tool or component name

Do	Don’t
The `flux` tool bootstraps and provisions Flux controllers in a cluster.	`flux` tool bootstraps and provisions Flux controllers in a cluster.
The Source controller manages resources.	Source controller manages resources.

Use a general descriptor over a component name

Do	Don’t
The Flux Source controller offers an OpenAPI spec.	The source-controller offers an OpenAPI spec.

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

Do	Don’t
Set the value of `imagePullPolicy` to Always.	Set the value of `imagePullPolicy` to “Always”.
Set the value of `image` to nginx:1.16.	Set the value of `image` to `nginx:1.16`.
Set the value of the `replicas` field to 2.	Set the value of the `replicas` field to `2`.

Code Snippet Formatting

Don’t include the command prompt

Do	Don’t
flux get kustomizations	$ flux get kustomizations

Separate commands from output

Verify that your cluster satisfies the prerequisites with:

flux check --pre

The output is similar to this:

► checking prerequisites
✔ kubectl 1.18.3 >=1.18.0
✔ kubernetes 1.18.2 >=1.16.0
✔ prerequisites checks passed

Fluxcd.io Word List

A list of Flux-specific terms and words to be used consistently across the site.

Term	Usage
Flux	Flux should always be capitalized.
On-premises	On-premises or On-prem rather than On-premise or other variations.
Multi-tenancy	Multi-tenancy or Multi-tenant rather than Multitenancy or other variations.

Shortcodes

Hugo Shortcodes help create different rhetorical appeal levels.

Surround the text with an opening and closing shortcode.

Use the following syntax to apply a style:

{{< note >}}
No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
{{< /note >}}

The output is:

Note: The prefix you choose is the same text for the tag.

Note

Use {{< note >}} to highlight a tip or a piece of information that may be helpful to know.

For example:

{{< note >}}
You can _still_ use Markdown inside these callouts.
{{< /note >}}

The output is:

Note: You can still use Markdown inside these callouts.

You can use a {{< note >}} in a list:

1. Use the note shortcode in a list

1. A second item with an embedded note

 {{< note >}}
 Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](https://kubernetes.io/docs/contribute/style/style-guide/#common-shortcode-issues).
 {{< /note >}}

1. A third item in a list

1. A fourth item in a list

The output is:

Use the note shortcode in a list
A second item with an embedded note

Note: Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See Common Shortcode Issues.
A third item in a list
A fourth item in a list

Caution

Use {{< caution >}} to call attention to an important piece of information to avoid pitfalls.

For example:

{{< caution >}}
The callout style only applies to the line directly above the tag.
{{< /caution >}}

The output is:

Caution: The callout style only applies to the line directly above the tag.

Warning

Use {{< warning >}} to indicate danger or a piece of information that is crucial to follow.

For example:

{{< warning >}}
Beware.
{{< /warning >}}

The output is:

Warning: Beware.

Markdown elements

Line breaks

Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level (or the title) without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better.

Headings

People accessing this documentation may use a screen reader or other assistive technology (AT). Screen readers are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.

Do	Don’t
Update the title in the front matter of the page or blog post.	Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading.
Use ordered headings to provide a meaningful high-level outline of your content.	Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.
Use pound or hash signs (`#`) for non-blog post content.	Use underlines (`---` or `===`) to designate first-level headings.
Use sentence case for headings. For example, Clone the git repository	Use title case for headings. For example, Clone the Git Repository

Paragraphs

Do	Don’t
Try to keep paragraphs under 6 sentences.	Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.
Use three hyphens (`---`) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section.	Use horizontal rules for decoration.

Links

Do	Don’t
Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See Check required ports for more details.	Use ambiguous terms such as “click here”. For example: Certain ports are open on your machines. See here for more details.
Write Markdown-style links: `[link text](URL)`. For example: `[Docs from the ground up](/contributing/docs/writing-docs.md)` and the output is Docs from the ground up.	Write HTML-style links: `<a href="/contributing/docs/writing-docs" target="_blank">Docs from the ground up</a>`, or create links that open in new tabs or windows. For example: `[Docs from the ground up](/contributing/docs/writing-docs){target="_blank"}`

Lists

Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list. Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.

End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.

Note: Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.
Use the number one (1.) for ordered lists.
Use (+), (*), or (-) for unordered lists.
Leave a blank line after each list.
Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

Tables

The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. A table caption is used to create a descriptive title for a data table. Assistive technologies (AT) use the HTML table caption element to identify the table contents to the user within the page structure.

Add table captions.

Content best practices

Use present tense

Do	Don’t
This command starts a proxy.	This command will start a proxy.

Use active voice

Exception: Use passive voice if active voice leads to an awkward construction.

Do	Don’t
You can explore the API using a browser.	The API can be explored using a browser.
The YAML file specifies the replica count.	The replica count is specified in the YAML file.

Use simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”

Do	Don’t
To create a ReplicaSet, …	In order to create a ReplicaSet, …
See the configuration file.	Please see the configuration file.
View the pods.	With this next command, we’ll view the pods.

Address the reader as “you”

Do	Don’t
You can create a Kustomization by …	We’ll create a Kustomization by …
In the preceding output, you can see…	In the preceding output, we can see …

Avoid Latin phrases

Prefer English terms over Latin abbreviations.

Do	Don’t
That is	i.e
For example	e.g.

Exception: Use “etc.” for et cetera.

Patterns to avoid

Avoid using we

Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.

Do	Don’t
Version 2 includes …	In version 2, we have added …
Flux provides a new feature for …	We provide a new feature …
This page teaches you how to use Kustomizations.	In this page, we are going to learn about Kustomizations.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Do	Don’t
Internally, …	Under the hood, …
Create a new cluster.	Turn up a new cluster.

Avoid statements about the future

Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.

An exception to this rule is documentation about announced deprecations targeting removal in future versions.

Avoid statements that will soon be out of date

Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.

Do	Don’t
In version 2, …	In the current version, …
The Image Update Automation feature provides …	The new Image Update Automation provides …

Avoid statements that assume a specific level of understanding

Avoid words such as “just”, “simply”, “easy”, “easily”, “basically” or “simple”. These words do not add value.

Do	Don’t
Include one command in …	Include just one command in …
Commit the Kustomization …	Simply commit the Kustomization …
You can remove …	You can easily remove …
These steps …	These simple steps …

Contributing: Google Season of Docs 2023

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

Flux is interested in applying to the 2023 Google Season of Docs to improve the documentation experience for our users and contributors. Below is our project ideas, if you have any questions, please reach out to Kingdon Barrett or Tamao Nakahara on CNCF Slack.

Timeline: https://developers.google.com/season-of-docs/docs/timeline

Improving the Flux User Onramp

About Our Organisation

Flux is a tool for keeping Kubernetes clusters in sync with sources of configuration (like Git repositories and OCI artifacts), and automating updates to configuration when there is new code to deploy.

Flux was created in 2016 and helped to formalise GitOps, or “Operations by Pull Request” as industry standard. In 2020 a rewrite of the project was started which helped to drastically modernise the code base and make new use-cases possible. The Flux project has become center of a rich ecosytem of GitOps solutions. Its controllers have become the basis for products, services and other tools. That’s why the project is seeing contributors from end-user companies, integrators and e.g. cloud vendors.

Flux is used by SREs, Platform Engineers, Architects and Developers. GitOps is the natural evolution of configuration as code. Organisations moving to Flux can deal with infrastructure at scale more easily, and allow their developers to focus on code, not on deployment problems.

Flux is licensed under the Apache License 2.0 license and is a graduated Cloud Native Computing Foundation (CNCF) project, used in production by various organisations and cloud providers.

About The Problem

Flux users come with different amounts of background knowledge to the project. Some have been using Kubernetes in earnest for some time, others don’t. Understanding the core concepts is critical to your success as a user installing Flux.

Other users are past the hurdles of the initial setup, but are looking at ways to simplify operations or to further automate processes. The docs currently contain most of what users need, the information might be just a bit hard to find. Reflecting the different stages of preparation, knowledge and state of implementation clearly in the navigation and information architecture will be beneficial.

Solving the problem will help our users find their way around more easily, they will have a more seamless experience and feel more self-effective. For us as a community, it will likely result in having to respond to less support requests.

Project Scope

In this project we would like to accomplish the following:

Part 1: Improve the navigating experience

Review the navigation / information architecture of the Flux documentation and assess to which stage of the users’ adoption journey the content belongs.
Write up a plan to recategorise relevant documentation.
Collect feedback on the new IA. Voices from Flux developers and users should be heard.
Implement plan, place relevant redirects. Implement link-checking.
Background information: #717, #718 (further thoughts #72, #120)

Part 2: Help understanding core concepts better

Talk to Flux developers and folks doing online support and get an idea of which Flux concepts are least understood and which basic knowledge is missing when interacting with new Flux users.
Review Core Concepts documentation, review flow of beginner docs.
Close potential gap in core concepts documentation. Refer to core concepts in documentation where appropriate.
Background information: #111, #493, #760, #783

Part 3: Installing Flux - could this be easier?

Understand overlap between “Installation”, cheatsheet entries and current “use-cases” docs.
Review how other projects deal with this in their documentation. “Tasks” are often a concept used.
Review Installation docs - should they be broken up? Are references between these and others docs missing, e.g. the cheatsheets and CLI reference?
Background information: #523

Measuring the success

The Flux developers spend a lot of their time on supporting Flux users and often it takes a while to discover the misunderstanding of a new user. That’s why we ideally would like to see the number of support requests go down and get the sense that users can more easily “help themselves”.

We get support requests through different channels, and e.g. Slack does not make it easy to measure, especially as we are in a growing field and have a growing user-base. Still we want to monitor the number of Github discussions and Slack requests and compare with the previous months and hope for a reduction 20% number of requests.

We also want the number of broken links to be 0.

We also want the updated navigation demonstrated to community and see a positive result of a poll about the new navigation experience.

Timeline

Dates	Action Items
May	Orientation: get to know the team. Familiarise yourself with `fluxcd/website` code and documentation structure.
June	Review navigation of docs of other CNCF projects. Draft a new proposal for the docs structure (cf. previous proposal). Create PR, ask team and community for feedback.
July	Finish navigation, test redirects and see if there are broken links. Talk to Flux team to figure out contention points and common questions of new users. Review flow of “beginner docs”.
August	Analyse “beginner docs”. Create plan for where core concepts should go into more detail. Work with Flux maintainers and contributors to write enhance the core concepts documentation.
September	Integrate work and ask for feedback from community. Celebrate success so far - get a nice blog post on the website!
October	Review overlap between Install docs, cheatsheet entries and use-cases. Compare with other projects. (Hopefully with what’s been done in June, it will be easier to distinguish Day 1 from Day 2 tasks.) If there is a lot more work to be done to e.g. break up pieces into “tasks”, maybe focus on low-hanging fruit instead. Ask for feedback again, publish.
November	Tidy up loose ends. Celebrate with another blog post on the website!

Project budget

Budget item	Amount	Running Total
Technical writer audit, update, test, and publish new documentation	8000.00	8000.00
Project t-shirts (10 t-shirts)	250.00	8250.00
TOTAL	8250.00

Additional information

Previous experience with technical writers or documentation: End of November 2021 the Celeste Horgan of the CNCF Tech Docs team assessed the Flux documentation. Some of the identified areas were addressed since then. Some of the findings are key issues we want to tackle as part of this proposal.

Previous participation in Google Season of Docs, Google Summer of Code or others:

Flux has not participated in any of these initiatives, so we are looking forward to being part of this (if chosen) and work together with the wider Docs community!

Getting Started

If you are interested in participating in Google Season of Docs as a technical writer, please do the following:

Join the #flux-contributors channel on CNCF Slack.
Review this project proposal and familiarise yourself with the documentation website. Particularly the sections Core Concepts, Get Started and Installation are read by our users all the time. Getting a general sense of the documentation structure of the organisation will be of help as well.
You will need some familiarity with Cloud Native technologies such as Kubernetes, so you can more easily understand the problems and background of users.
Talk to us on Slack, introduce yourself - we are happy to tell you more.