Make docs more newbie-friendly

[samjewell]

Excuse me for making some suggestions cold, but coming to this repo cold (and having some prior knowledge of Grafana and Grafana Cloud, inc. Cortex and Synthetic Monitoring) I think we could make some improvements to make this repo easier to understand and use. In vague priority order:

1. Explain why Grizzly exists, and what it is (and is not) meant to be used for. What tools is it similar to (is it similar to Terraform, for example?) Does it include compilation of JSonnet?
2. Replace "CORTEX" with "HostedPrometheus" in docs and env-vars. You can get quite far with Grafana Cloud never knowing what "Cortex" is, as everything in the UI talks about (hosted) prometheus.
3. grr listen no longer works in Grafana 8! Ack this in the docs. Give an alternative way for people to fetch a remote resource and write it to JSON. I tried grr get [res_type.uid] > res_name.json, but found the output was actually yaml! Offer command-line flags to
   1. Output json instead of yaml, and
   2. pass an output file to save directly to
4. Include examples with the required env-vars. I wasn't sure whether you wanted the CORTEX_ADDRESS to be the write-endpoint, with /push suffix
5. Say what role the token needs, when asking the user to create CORTEX_API_KEY and GRAFANA_TOKEN. I went with "admin", but I'd rather give less permission if possible.
6. Remove or comment out grafanaDashboardFolder:: 'my-folder', from the Grafana Dashboard Example. This breaks the example, which only worked when I commented-out this line.
7. Update the "Next, we need to interact with Grafana" section: It says GRAFANA_HOST is needed, but I didn't need it.
8. Docs sometimes use uppercase, sometimes lowercase for "dashboard": grr listen dashboard.my-uid my-dash.json vs grr get Dashboard.my-uid. I'd prefer if these were consistent, or at least if the difference was explained somewhere.
9. When I use grr apply the message I see has a slash separator. It should use a dot instead, to match the grr get syntax. ie. SyntheticMonitoringCheck/grafana-com added makes me try grr get SyntheticMonitoringCheck/grafana-com, at which point I see UID must be <provider>.<uid>

[malcolmholmes]

Sam,

This is great feedback.

1. I've just merged a PR including some new docs, that are linked from the README. That should give a great deal more background as to how Grizzly is used.
2. Initially, Grizzly just consumed cortextool, so defers these envvars to that tool. I agree we need to describe this a "hosted prometheus" as a generic category.
3. Yep, acknowledged. That needs fixing
4. Very good idea
5. Ditto
6. Replaced by new docs
7. I think referenes to GRAFANA_HOST have gone now
8. Yes, part way through development, we switched to using Kubernetes style objects, which have a kind which is capitalised. You are right that this isn't properly documented, even in the new docs. Will add it.
9. Yes, the . vs / separator question is annoying. We need consistency. If we stick with dots, then in the case of Prometheus rules, we have PrometheusRuleGroup.$NAMESPACE.$NAME, which I think can work. So (a) decide that it will just be dots, then (b) make it so.

Thanks for these comments. You're seeing outcomes of layers of learning/experimentation as this codebase has formed. You are right that these need resolving (at least, the ones that hadn't been fixed yet!)

[malcolmholmes]

Only task remaining from the above list:

• Say what role the token needs, when asking the user to create CORTEX_API_KEY and GRAFANA_TOKEN. I went with "admin", but I'd rather give less permission if possible.

[malcolmholmes]

Created #414 for the above. Closing this issue now.