Reorg docs IA

[dholbach]

Ref: #72, #717, #718

This is likely going to be a draft PR for a while. For now I'd like to make this PR represent a simple PoC based off of #717 (comment) - so no big moving of docs just yet. More of a place to try a couple of things and review the information architecture (IA) together.

→ https://deploy-preview-845--fluxcd.netlify.app/docs/

[dholbach]

[dholbach]

The above represents the simple changes for now. So essentially just navbar changes including redirects. Anchors should continue to work. No content moved.

What does everyone think so far?

[kingdonb]

I don't see any problems and in general I think this is more accessible 🎉

I've mainly reviewed the TOC that you posted earlier, it seems like a reasonable organization structure. It seems like fewer top-level entries, but after counting I'm pretty sure both versions have 13 top-level entries. There are things nested more deeply and it's clearer when you need to access each doc. I think it will be less difficult to find what you're looking for, but I will try using the preview version for a little while and have to see how I feel after that...

[dholbach]

What the PR shows so far potentially be a first step, a second could be the reader flow from landing page, to /docs or /docs/getting-started and /docs/concepts, etc clearer and nicer, maybe also explaining the nav even clearer (and or add 'day 1' / 'day 2' to the nav).

[scottrigby]

Overall looks great!

My only concern is that right now "platforms" appears only under "installation", but the use cases for specific platforms we have now apply to more than just installation 🤔 Should there be a top level platforms section, which summarizes info for each major platform, and links to the other docs as appropriate (under installation > platforms, operations > platforms, workflows > platforms)? I know people will be looking for this.

[dholbach]

This is based off of #717 (comment) - which to me seemed to bring more clarity from a nav and organisational point of view. If you have other suggestions on what to place where, please let me know.

What we could (and should) do separately is apart from the navigation: make better use of the /docs/ and /docs/installation landing pages more and build a clearer flow for the reader. For example could we place project/platform logos in the docs to get the reader's attention and direct them to the right place.

[dholbach]

Feedback from @wwentland

Organisation

There is a lot of very good content and I personally consider the documentation to be very helpful, if a little hard to navigate due to its organically grown nature.

Proposal by @danports in #717 (comment)

• Nice separation of content into different sections focused on user/reader intent
• I think this would benefit from standardising on either “Noun” or “Verb” section titles (where appropriate)
• Soft personal preference on “Verb” ones, but consistency most important
• “Installation” vs “Installing” / “Integrating” vs “Integration”
• We might want to introduce a “Reference” section, subsuming CLI and Components reference style documentation
• I specifically like the separation in Getting started (day 1), and typical operations (day 2) content
  • Day 2 / Operations section would be perfect for discussing 2.0 HA topics also

This proposal

• Nice adaptation of the earlier proposal with the goal of not introducing too many changes to the underlying content/keeping anchors working
• Migration from Flux v1 too prominent IMHO (increasingly less important)
• Some sections assume prior knowledge
  • “Flagger” would be better as “Progressive Delivery” or “Progressive Delivery with Flagger”
  • Toolkit Components would be much better as part of the “Workflow” or “How to build custom things w/ Flux” section
  • Toolkit Dev Guide would fit much better in either a “Flux as SDK” or “Integrating” section