New docs structure

[dholbach]

In #1130 @squaremo brought up the proposal to use the following structure for docs:

1. have one file for each of {fluxd, helm-operator} with setup instructions
2. document and link to troubleshooting and advanced config, in their own files
3. reference docs for daemon flags, helm-operator flags, fluxctl

E.g. site/using.md could be just about fluxctl.

[dholbach]

.
├── CHANGELOG-helmop.md                            Changelog: helm operator
├── CHANGELOG.md                                   Changelog: fluxd + fluxctl
├── chart
│   ├── flux
│   │   └── README.md                              Actual docs for Helm chart (options, common use, config)
│   └── README.md                                  Placeholder doc, can go?
├── internal_docs
│   └── releasing.md                               Release process for flux
├── README.md                                      Top-level "flux home"
└── site
    ├── building.md                                Building flux from source
    ├── daemon.md                                  fluxd explanation and options
    ├── faq.md                                     Flux FAQ
    ├── helm
    │   ├── get-started.md                         Flux helm "hello world" tutorial
    │   ├── helm-integration.md                    Flux helm spec, cf #1205
    │   └── helm-integration-requirements.md                "
    ├── how-it-works.md                            High-level flux goals, merge into top-level README?
    ├── images
    │   └── deployment-pipeline.png
    ├── installing.md                              Install redirect to either Helm or Standalone, remove?
    ├── introduction.md                            Discussion of high level features, merge elsewhere?
    ├── monitoring.md                              Sparse, merge elsewhere?
    ├── requirements.md                            Reqs (git repo) and (few) limitations, merge elsewhere?
    ├── standalone
    │   ├── installing.md                          Flux standalone "hello world" tutorial, rename to get-started?
    │   └── setup.md                               Some notes on customising the setup, merge elsewhere?
    ├── troubleshooting.md                         Some troubleshooting clues, feels a bit FAQ-y
    ├── upgrading-to-1.0.md                        For hysterical raisins
    └── using.md                                   fluxctl docs, should be renamed?

[dholbach]

After #1357 landed, the relevant bits are:

.
└── site
    ├── building.md                                Building flux from source
    ├── daemon.md                                  fluxd explanation and options
    ├── faq.md                                     Flux FAQ
    ├── helm-get-started.md                        Flux helm "hello world" tutorial
    ├── helm-integration.md                        Explanation of Helm integration
    ├── helm-operator.md                           Details about the Helm operator
    ├── how-it-works.md                            High-level flux goals, merge into top-level README?
    ├── installing.md                              Install redirect to either Helm or Standalone, remove?
    ├── introduction.md                            Discussion of high level features, merge elsewhere?
    ├── monitoring.md                              Sparse, merge elsewhere?
    ├── requirements.md                            Reqs (git repo) and (few) limitations, merge elsewhere?
    ├── standalone
    │   ├── installing.md                          Flux standalone "hello world" tutorial, rename to get-started?
    │   └── setup.md                               Some notes on customising the setup, merge elsewhere?
    ├── troubleshooting.md                         Some troubleshooting clues, feels a bit FAQ-y
    ├── upgrading-to-1.0.md                        For hysterical raisins
    └── using.md                                   fluxctl docs, should be renamed?

Structure-wise moving things out of the standalone directory could be done. The rest is slowly getting closer to what Michael suggested at the beginning.

[dholbach]

@squaremo Can you maybe help break this up into more manageable tasks? (I'm happy to file separate issues for them.)

Looking at what we have and comparing this to comment 1, I can see:

• Create a doc exclusively for fluxd. (Which sections do we use as source?)
• Move docs from standalone directory into their own space. Use similar naming as in the rest of the docs.
• Review reference bits (fluxd, helm-op, fluxctl, chart) and decide if they need their own space?
• Rename using.md to fluxctl.md.

[hiddeco]

A thing I noticed while looking for information sometimes is that the long documentation pages like using.md do not have an index.

I think having an index at the top of these pages can help people with:

a) seeing if they opened a relevant page for the information they're looking for
b) navigating to the relevant piece of information on the page (scrolling and eye-scanning can be exhausting)

[dholbach]

Agreed @hiddeco. It'd be good to add table of contents to the larger pages. AIUI there's no automatic support in Github Markdown for this as of yet. Shall we move this to a separate issue?

[dholbach]

I went over the docs again and feel that

• daemon.md about fluxd is in good shape - it discusses the daemon's flags and its responsibilities. I added a link to standalone-setup.md to make sure people find how to configure the most relevant bits.
• With the current setup, the reference bits look good to me and are more easily findable then when we filed this issue.

I'll push a PR in a bit which just adds a couple of links and I feel this issue can be finally closed with this.

If we feel we need a clearer (or combined?) reference section, let's take it to another issue.