Restructure docs around how-to, reference, tutorials, and explanation

[squaremo]

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.

[alisondy]

I've started taking a look at this,
had something similar in mind like with the k8s docs for Page content types

• Tasks
  • How to do a single thing, in a brief sequence of steps
  • Minimal explanation but link out to concepts that provide the background info
• Tutorials
  • Accomplish a goal large than a single task
  • Can provide brief surface level explanations but links out to docs explaining more conceptual things
• Concepts
  • Explain aspects of Flux
  • What role a controller takes on in a cluster
  • Links out to tasks and tutorials
• Reference
  • API reference
  • CLI

[alisondy]

Also another note that is related to this is

we have made some sprawl in some areas, for instance

if I had a question like How do I do x with Flux i could find the answer in all these places

https://fluxcd.io/docs/guides/helmreleases/
https://fluxcd.io/docs/use-cases/helm/
https://fluxcd.io/docs/components/source/helmcharts/
https://fluxcd.io/docs/components/source/helmrepositories/
https://fluxcd.io/docs/components/helm/helmreleases/

[alisondy]

Also, I think this may be a major blocker on documentation refactoring and bringing on new docs contributors.

[squaremo]

Tutorials

• Accomplish a goal large than a single task
• Can provide brief surface level explanations but links out to docs explaining more conceptual things

Crucially, tutorials guide you through a process with the aim of learning about using Flux; as contrasted with Tasks (or How-tos), which are recipes to follow to get some practical result.

For example:

Task: How to set Flux up to scan images in ECR
Tutorial: See how image automation works in Flux

[alisondy]

See how image automation works in Flux

From this I don't know what I'm getting out of this, and it could be duplicating information in a concept or explanation page about how the Image Automation controller works, and the role it plays in the cluster.

Tutorials still teach you how to do something - theres still an end goal, the only difference is more context is given,
whereas a task is more like a procedure.

so something like
Tutorial: Example: Set up image automation for PodInfo

[squaremo]

OK, bad example on my part. The point is that the difference is that tutorials are to teach you about something, how-tos are a recipe for some specific, technical result.

[alisondy]

That sounds right - 👍

[dholbach]

Feedback from @wwentland

Deep content

As discussed during KubeCon, there is a lot of valuable and quite specific content hidden in the sections that discuss the various controllers (kustomize, helm, …).

It would be great to make this content more obvious, by differentiating more between “Reference” (Kustomize controller spec) and “Workflows” more explicitly

• Reference: Exhaustive list of options/spec
• Workflows: Complete/opinionated examples of achieving a specific goal (maybe highlighting alternative approaches where possible)

One of the main problems with this deep content are existing links to anchors that might not resolve later.

[kingdonb]

One of the main problems with this deep content are existing links to anchors that might not resolve later.

I would like to address this systematically, I built a reference attempt in #1630 then put it on the shelf and haven't looked at it for a while. We can revisit it in a bit, but in the mean time let's try to figure out where we've broken links if we're breaking any more, and add the redirects where we can.