breakout installation in favor of individual guides

[alisondy]

this is a tracking issue

Current PRS in Flight

#521 Install Guides
#520 Uninstall Guide
#519 Upgrade Guide
#518 Bootstrap guides

TODO

• Redo page weights
• Remove installation.md - Blocked by Create separate install guides for Linux, Mac and Windows #521,Add uninstall guide #520,Add upgrade guides #519,Break out bootstrap on installation page into separate guides #518
• Add customize flux manifests doc
• adjust title and linkttitle for some of the docs

notes

• Redirects for installation.md may end up being alot of work, maybe investigate creating a 404 page with links to common areas

[stefanprodan]

I propose we make installation into a section with cli/bootstrap/upgrade/uninstall as subsections. This way no links will break and we don't hide the install content under guides.

[alisondy]

I propose we make installation into a section with cli/bootstrap/upgrade/uninstall as subsections. This way no links will break and we don't hide the install content under guides.

• installing the CLI is a prereq to running tasks like bootstrap, upgrade, and uninstall.
• tasks like bootstrap, upgrade, and uninstall pertain to the lifecycle of a flux deployment

Perhaps something like?

 /install-the-flux-cli
 /Deploy and Manage Flux Components
      /bootstrap flux
      /upgrade flux
      /uninstall flux
      /customize flux

[stefanprodan]

installing the CLI is a prereq to running tasks like bootstrap, upgrade, and uninstall.

Yes we can write the CLI steps in the installation/index.md then all others will be under installation.

[alisondy]

ok sounds good

[alisondy]

no doesn't sound good actually

• Windows OSX and Linux are separate guides
  this is because in the former format people had to sift through all the different options to find the ones relevant to their operating system

if we collate them all into one page it'll be long and repetitive.

or it will be something like this

/installation
     _index.md
     windows.md
     linux.md
     osx.md
     /bootstrap
           ...
      /upgrade
           ..
      /uninstall
           ...

[stefanprodan]

The last structure you posted looks good to me 👍

[stefanprodan]

Another option would be:

/installation
  _index.md
  /cli
    macos.md
    linux.md
    windows.md
 /bootstrap
 /upgrade
 /uninstall

[alisondy]

When you mentioned previous structure, were you referring to this one?
I'd be happy to ahead with this:

 /Install-the-flux-cli
       _index.md
       windows
       osx
       linux
 /Deploy and Manage Flux Components
      /bootstrap flux
           ...
      /upgrade flux
           ...
      /uninstall flux
           ...
      customize flux

Burying all this information under one ambiguous heading "installation" leaves way more effort on the reader to figure out where they can find the information for the specific thing they want to do. "Install the CLI" and "Deploy and Manage Flux Components" are clearly defined names which aren't vague

[scottrigby]

This also lgtm, with just a small change.

Remember when we were looking at the AWS guides model, where the pages are shorter and so when you search you see a list of results specific to what you need? I feel the structure above is very similar to that strategy and if we roll that out across the docs that could be a very good thing for end users.

The /Deploy and Manage Flux Components section lgtm from this angle, but suggesting one small adjustment to pages under /Install-the-flux-cli:

 /Install-the-flux-cli
       _index.md
-       windows
-       osx
-       linux
+       Install CLI on windows
+       Install CLI on osx
+       Install CLI on linux
 /Deploy and Manage Flux Components

This way when someone types install or cli into search, they'll see a dropdown select of matching pages like:

"CLI" or "install"
    install CLI on windows
    install CLI on osx
    install CLI on linux

instead of only:

"CLI" or "install"
    windows
    osx
    linux

[alisondy]

Update on this work
~~ need to reweight all the pages ~~
can a seprate branch be made to take in all 4 of these major changes, made separate branch
~~ then a pr onto that branch to redo page weights ~~
~~ then a pr from that branch into main to apply new page weights and pages. ~~

Either way it ends up a big PR onto main.

I've separated each section of changes into individual commits

[alisondy]

Changed the approach

Made every section of major changes into individual commits

• install
• upgrade
• bootstrap
• uninstall
• remove installation.md
• reweight

Can review each commit individually instead of having to review 4 different PR's

#530

If you don't want to be overwhelmed by every single file edited, I recommend browsing by individual commit for each of the changes.

[kingdonb]

The installation guide has been updated to match the idea proposed here,

https://fluxcd.io/flux/installation/

Instead of telling everything, it covers just the prerequisites, the CLI installation, and an overview of bootstrap with links to the specific guides. All of the details that are cloud-provider specific or repository-host specific are now contained within the sub-guides, which are each comprehensive.

(I'm going through the notes for GSoD and issues linked in https://fluxcd.io/contributing/docs/google-season-of-docs-2023/ to figure out what parts remain that we still need to focus on.)

Another subsection was added, Configuration: https://fluxcd.io/flux/installation/configuration/ - this covers all the details like Customizing Flux Manifests, feature flags, security hardening and scaling. There are no more bootstrap cheatsheets.