It'd be great if we could find a gentle way to raise awareness of the content below the fold. One that doesn't get into the way of the animation too much.

It'd be good to point out that we are working on the GitOps Toolkit, a broader and more modular approach to GitOps and "flux v2" which will be composed from the GOTK. We might want to link to an announcement, a presentation, to toolkit.fluxcd.io and a get started doc.

Maybe also mention that "flux v1" is in maintenance mode now.

Before we merge #110 we should at the very least

• check all pages from toolkit.fluxcd.io are successfully moved over
• run a link checker over the entire site

Invite Flux 2 end users to an interview style discussion about their GitOps journey, which could then be edited and made available publicly.

Selected interviews could be made available on the Flux blog, or linked somewhere on the website.

Draft: https://docs.google.com/document/d/15dn8_TDJeoiULAjv5YpLIRG1Mwd5LnCL4uTNG7NuSMk/edit#

@hiddeco @scottrigby We talked about renaming the blog series. The current focus of the series is "road to flux v2" and we're in a monthly cadence for them. Anything you'd like to see instead of "January update" (see last post as an example)

Hello everyone,

it would be nice to be able to subscribe to the blog (https://fluxcd.io/blog/) via any RSS/atom reader.
any plans for this?

We should potentially borrow https://github.com/fluxcd/flux2/blob/main/.github/workflows/docs.yaml and plug it into our Makefile somewhere, so we have all relevant CRD docs available too.

Potentially check if we need to add frontmatter?

The recording shows gotk --help, it'd be great if it showed the output of flux bootstrap instead.

hack/import-flux2-docs.sh adds frontmatter for both imported markdown and html docs.

Now it should remove the title after having added frontmatter title entry. A good example for this now is /docs/components/source/gitrepositories/.

@hiddeco says

But there is other content that needs to be worked on.
"Overview" is for Flux v1.
Tagline is for Flux v1.

See here misspelling error for canary.

incorrect: canaray
correct: canary

From #81:

The "notification area" is getting very crowded now. Let's figure out a way to have a news section that sources bits from somewhere else and takes up more clearly defined space, e.g. 3 stickied bits of info (like flagger-move, maintenance mode) plus the last 3 blogs posts...?

Mention that /f/flux is in maintenance mode and won't return new features

Create adopters page for Flux 2 users.

We should add a progressive delivery section to the homepage and link to Flagger docs. The PD section content can be adapted from https://flagger.app

@alisondy I seem to remember you had search enabled in your demo of docsy. Can we bring it back?

@staceypotter and I talked about updating the resources section on https://fluxcd.io#resources

E.g. click on it and it takes you straight to GitHub.

Theoretically this is easy to do, but some docs come from f/flux2, so this will be a little more complicated to do.

[daniel@reef fluxcd.io ]$ git grep -i hugo netlify.toml
netlify.toml:HUGO_VERSION = "0.55.6"
[daniel@reef fluxcd.io ]$ 

Using recent hugo

[daniel@reef fluxcd.io ]$ hugo version
Hugo Static Site Generator v0.75.1/extended linux/amd64 BuildDate: 2020-09-15T14:28:18Z
[daniel@reef fluxcd.io ]$ hugo server 
port 1313 already in use, attempting to use an available port
Start building sites … 
Built in 13 ms
Error: Error building site: TOCSS: failed to transform "sass/style.sass" (text/x-sass): SCSS processing failed: file "stdin", line 10, col 9: malformed URL 
[daniel@reef fluxcd.io ]$ 

Using an older version of hugo

[daniel@reef fluxcd.io ]$ ./hugo version
Hugo Static Site Generator v0.57.0-9B00E647/extended linux/amd64 BuildDate: 2019-08-14T08:12:12Z
[daniel@reef fluxcd.io ]$ ./hugo server 
port 1313 already in use, attempting to use an available port

                   | EN  
+------------------+----+
  Pages            |  3  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  8  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

Total in 169 ms
Watching for changes in /home/daniel/dev/fluxcd.io/{assets,content,layouts,static}
Watching for config changes in /home/daniel/dev/fluxcd.io/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:38783/ (bind address 127.0.0.1)
Press Ctrl+C to stop

@alisondy started work on this in #110 - looking good already!

Update for current needs. See earlier work Scott & Leigh did on high-level personas.

Separate issues/PRs should link to this umbrella issue. Examples:

• Helm users @scottrigby
  • intro page fluxcd/flux2#1255
  • how to get started
  • Helm migration intro page (this is linked from use case intro page)
  • 1 or 2 repos (could maybe add use cases from Kingdon and Scott's kubecon talk)
  • how to contribute to helm controller
• Kustomize users
  • manifest generation fluxcd/flux2#1200
  • Kustomize intro page?
• Azure users @stealthybox fluxcd/flux2#1064
  • Ask AKS/MS Arc folks at microsoft to look at this?
• Open Shift users @chanwit
  • Flux Operator for Open Shift as well
• Jenkins users @kingdonb
• Terraform users @stealthybox
  • Flux installation method (there is a google cloud example added to terraform provider repo) @scottrigby
  • A Terraform reconciler controller idea
• Vault users @scottrigby & @kingdonb
• Jsonnet users
• Windows users

Across all guides we should establish a common structure for how it's written and make sure we follow this for all of them.

@scottrigby says

1. The ^^ were there really just to underline the short headers, as an easy way to reference the status of each (Flux 1, Flux 2 CLI, GOTK) at each milestone. Is it possible to underline those, or in some other way make them stand out from any bullets below?
2. Can the table content be top-justified for readability?
3. In mkdocs I was able to style these table columns to explicit percent widths: 4%, 32, 32, 32. Is that possible here too? See https://github.com/fluxcd/flux2/blob/main/docs/_static/custom.css#L119-L122

This is re: #110

Aside from the command-line reference, most of the documentation is under "Guides", and this is in danger of becoming a miscellaneous (and therefore not very helpful) classification. To give visitors a better chance of finding what they need, I suggest following the scheme now described at https://documentation.divio.com/introduction/; that is, to structure documentation around the four categories:

• how to guides show people how to accomplish a specific, practical task; e.g., how to migrate to the Helm controller
• reference materials let people look up the details of a command or API, e.g., what the flags are for flux create image
• tutorials aim to teach an aspect of the system, by giving people a step by step guide; e.g., the source-watcher dev guide
• explanations discuss a topic related to the system, so people can get a better understanding of it; e.g., "Core Concepts"

This gives a meaningful first dispatch point for docs visitors -- if they have a specific problem to solve, they can look under "how to", if they want to learn more by doing, they can follow a tutorial, and so on.

Once fluxcd/community#6 is resolved, we should point to the README from the /f/community repository as a good way into the community.

Compare https://toolkit.fluxcd.io/ to https://deploy-preview-110--fluxcd.netlify.app/docs/

Do we want to port things over?

No explanation required here, I hope.

Now that #74 is sorted, we might want to look into automating this. Would it be e.g. possible to have a cron job which runs the hack/gen-content.sh script and create a PR if there's a diff?

The TOC on the right hand side of https://toolkit.fluxcd.io/guides/helm-operator-migration/ is very crowded, let's add a mini-TOC at the top of the document to provide links to:

• discussion of breaking changes
• api spec changes
• migration strategy
• FAQ

docsy vs. mkdocs

Re: #110

We still have a couple of blocks we want to add to the main page from fluxcd.io - let's see how we can add them to the site using docsy most easily.

making a a note of this

The colors we use in our website don't match the ones in our branding

// Flux color palette
$flux-darkest-blue: #3570e3
$flux-dark-blue: #2a7de3
$flux-lighter-blue: #1b8de2
$flux-light-blue: #0096e1
$flux-black: #1a1a1a
...
$primary: $flux-dark-blue
$secondary: $flux-light-blue
$dark: $flux-black

from https://branding.cncf.io/projects/flux/

• Twitter: https://twitter.com/fluxcd
• LinkedIn group: https://www.linkedin.com/groups/8985374/

While I was mocking the structure of the homepage, I did not spend much time on padding and/or margin between elements. This is most obvious in the "features" section, where the spacing between icons and/or text is not optimal.

Disable docs for now, so we can prep a drop-in replacement for current fluxcd.io.

Maybe also point to

• toolkit.fluxcd.io
• docs.fluxcd.io
• docs.fluxcd.io/projects/helm-operator

so people still find their docs

Explain what user options are if you need help with Flux projects.

We should point out

• FAQ/Troubleshooting Docs for individual projects
• clearly what the limits of community support are
• how to submit clear information if you really found an issue
• how to buy enterprise support (this would be open to companies who offer support around Flux and its technologies)

Since we draw from different sources, "edit this page" should link to the correct file in the correct repo. Example component CRDs are from the go code in each separate controller, which would be very difficult for new users to find.

Link to Slack inviter somewhere too: slack.cncf.io - I just talked to somebody to whom it was not obvious: "looks like this Slack is only for cool people".

fluxcd.io is suffering from tengbao/vanta#78 - it'd be good if we could figure out a solution or use a different background / illustration.

As discussed in fluxcd/flux2#367 we want to move the docs like so:

The proposal did not quite discuss what would happen with

• docs.fluxcd.io (v1 docs) and
• https://flagger.app (now part of /fluxcd)

Once we have a URL structure figured out for everything we can start implementing. Maybe we do this in 3 stages - first as discussed in the discussion linked above Flux v2 docs only.

So far we have published Flux updates on the Weaveworks blog, e.g.

• https://www.weave.works/blog/gitops-with-flux-v2
• https://www.weave.works/blog/flux-v2-september-update

This was done for the reason that 1) the WW blog exists and 2) has an existing audience and 3) the WW Marketing team was able to help with editing and promotion on social media.

We might want to have a more neutral home for updates?

As indicated in #114 we will have some cleaning up and beautification to do once all content blocks are brought back.

https://fluxcd.io/blog/ currently looks a bit bleak.

I think it could either

• show the full last 10 articles or
• show the 10 last articles and their featured image ... if that can be accomplished easily(?)

As this will become our hub for all website and documentation related things, the developer orientated README.md should be rewritten to welcome contributors of all kinds.

The kubernetes/website repository has a great example: https://github.com/kubernetes/website

At present we do not have any analytics enabled that require us to comply with GDPR and/or point people towards a privacy statement. It would however still be nice of us to tell people in the interest of transparency.

For this, a privacy page must be created and linked to in the footer. The contents of it could be as short as:

Note that we track visits to this website using Netlify server-side analytics. Because site activity is tracked anonymously without cookies or personally identifying information, Netlify Analytics is fully GDPR compliant.

As discussed in fluxcd/flux2#367.

Gradient of the hero elements should be changed to the one that is currently in use for the menu on https://docs.fluxcd.io, as it is a brighter / more vivid color combination.

background-image: linear-gradient(45deg, rgb(0, 150, 225) 0%, rgb(27, 141, 226) 24%, rgb(42, 125, 227) 53%, rgb(53, 112, 227) 78%, rgb(53, 112, 227) 100%);

We may want to incorporate this color change in the color palette defined in https://github.com/fluxcd/fluxcd.io/blob/next-gen/assets/sass/style.sass#L12-L15