Sections "Guides" and "Use cases" overlap

[dholbach]

From the CNCF Tech Docs assessment of our docs (cncf/techdocs#89):

Between the Guides and Use cases overlap a bit. The topics in these two sections are around installing and using Flux with a variety of different technologies. The names of both are somewhat vague which causes a lack of clarity for the reader: they need to click in to understand what each section is about, and even after doing so it isn't entirely clear.

Recommendations

Information architecture:

• Reorganize the Guides and Use cases:
  • Docs root
    • ...
    • Installation
    • Integrating Flux
      • Azure
      • OpenShift
      • Helm
      • Jenkins
      • Prometheus
      • Flux Notifications
    • Automation & GitOps
      • Ways of structuring your repositories
      • Setup webhook receivers
      • Sealed Secrets
      • Manage Kubernetes secrets with Mozilla SOPS
      • Automate image updates to Git
      • How to make sortable image tags to use with automation
      • GitHub Actions Manifest Generation
      • GitHub Actions Auto Pull Request

[dholbach]

Interesting point in #740 (comment)

I think it would be helpful if the Flux docs more clearly outlined day 1/day 2 operations, the GitOps workflow, and how Renovate fits into that. Right now, the Guides and the Use Cases sections are like cookbooks with a mish-mash of various recipes, which is a little bit confusing. I'd suggest reorganizing the contents of those sections into two new sections: Installation/Configuration (i.e. day 1) and Operations (i.e. day 2). Then I'd add an Operations subsection to discuss manual and automated upgrades via flux bootstrap, the GitHub Action, Renovate, etc. I'd probably put the Prometheus monitoring guide and migrations bits in the Operations section too.

[danports]

Yes, exactly, I was thinking about writing up a suggested docs outline, but it sounds like I was beaten to the punch. 😂 I think that outline could still use some improvement, though...I'll give it some thought.

[danports]

Here's a rough outline for a docs v2.0 based on a quick review of the existing docs - I'll update it if I have additional ideas. Thoughts?

• Get Started (bare minimum to get started - integrate with Core Concepts)
• Installation (day 1/performing a new install with no bells or whistles)
  • Structuring your Flux repositories
  • Platforms
    • AWS CodeCommit
    • Azure (move the bits about Azure Key Vault, etc. to managing secrets or other pages, just focus on installation here)
    • OpenShift
    • (others in existing docs)
• Operations (day 2/managing Flux)
  • Upgrades
    • Manually (via flux bootstrap, etc.)
    • Automatically via GitHub Action
    • Automatically via Renovate
    • Migrating from old versions
  • Notifications
  • Monitoring
  • Security
  • Managing incidents (e.g. suspend/resume)
  • Managing secrets
    • Sealed Secrets
    • SOPS
  • Pushing updates via webhook receivers (vs. pulling updates)
• Workflows (how to assemble the toolkit components to do something useful - this probably needs to be fleshed out a bit more)
  • Automating image updates (this could potentially be done with either Flux or Renovate - might be interesting to explore the pros & cons of the two options here)
    • Authentication
    • Sortable tags
    • Pull requests
  • Automating Helm releases (including automated upgrades with SemVer constraints in Flux and upgrades via PR with Renovate - much of this is in Use Cases/Helm right now)
  • Automating manifest generation
  • Integrating CI with Flux CD (from the existing Jenkins + Flux page - the concepts here aren't really specific to Jenkins; perhaps include CD validation with flux diff)
  • Managing multiple environments/clusters/tenants?
• Components (exhaustive documentation on all of the options for the components without any how to content, which should be in the sections above)
• CLI (exhaustive documentation on all of the CLI options)
• Integrating (guides for consuming the Flux API)
• Contributing (guides for developing Flux)
• FAQ

[dholbach]

Thanks @danports for your suggestion. I was out for a week and needed a bit of time to digest this. From what I see, this looks great. I'll bring it up with the rest of the maintainers and maybe with the CNCF Tech Docs folks as well... as it's going to be quite a re-shuffle of our docs. :-)

[dholbach]

Stefan gave some feedback: he liked the last proposal a lot, but we need to be careful about moving content, as links with anchors, e.g. /install#anchor2 can't be redirected clearly. So something to bear in mind.

[dholbach]

https://deploy-preview-845--fluxcd.netlify.app/docs/ has a preview build with the low-hanging fruit from Dan's proposal. Feedback would be welcome. (Note this is not a finished piece of work, just a PoC to get an idea of how this new, improved IA could work.)

[Neilblaze]

@dholbach, @danports Is it up for grabs? I'd love to incorporate a few feedback from y'all & then take a shot at it! :)

[danports]

I haven't done any work on this beyond writing the outline earlier - @dholbach has taken it farther than I did (thanks!).

[dholbach]

Thanks @Neilblaze for offering help. If you take a look at #845 it's my previous attempt, it's out-dated now, but might give an idea of how we could look at solving this issue.

[kingdonb]

We still have "Use Cases" and "Guides" which I'm hesitant to merge any further, because both lists are long, and a list that is twice as long would be very bad IMO. Helm appears in both lists. I think this is fine, PRs with ideas for how to organize the docs better are welcome, as long as we don't break any hard links.

It would be good to verify we haven't already broke some hard links without adding redirects (I'm afraid we may have)