Closed dholbach closed 9 months ago
Interesting point in https://github.com/fluxcd/website/issues/740#issuecomment-1031656530
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.
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.
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?
flux bootstrap
, etc.)flux diff
)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. :-)
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.
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.)
@dholbach, @danports Is it up for grabs? I'd love to incorporate a few feedback from y'all & then take a shot at it! :)
I haven't done any work on this beyond writing the outline earlier - @dholbach has taken it farther than I did (thanks!).
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.
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)
From the CNCF Tech Docs assessment of our docs (https://github.com/cncf/techdocs/pull/89):