Docs: Re-order, revise, review, and refactor Mimir documentation

[osg-grafana]

To see accurate status information about document development, see the Grafana Labs org-wide project #120.

Co-ordinate any changes to this list that follows with Jack and Ursula.

Refactor all Mimir documentation based on internal information architecture project underway by Docs Squad.

Thanks, @jdbaldry, for the collaboration on this list:

Proposed structure for technical documentation

• Collocate Query sharding with the Query-frontend component
• Move Contributing to top level of repository.
• TO FIGURE OUT: Where does an explanation of how to issue cross-tenant queries and alerting/recording rules fit

---

• About Grafana Mimir
• About tenant IDs #1109
• Getting started with Grafana Mimir
• Migrate to Grafana Mimir
  • Migrating from Cortex
  • Migrating from Thanos or Prometheus
• About authentication and authorization #1101
• About the architecture #999
  • About the hash ring #1272
  • About the key-value store #1273
  • About the memberlist protocol and gossip #1274
  • Compactor #1078
  • Distributor #1079
  • Ingester #1080
  • Querier #1081
  • Query-frontend #1082
  • Query-scheduler #1083
  • Store-gateway #1084
  • (Optional) Alertmanager #1013
  • (Optional) Overrides-exporter #1110
  • (Optional) Ruler #1085
• Grafana Mimir tools #1098
  • Tenant injector #1086
  • Compaction planner #1087
  • Mimirtool #1105
  • Trafficdump #1106
  • Query-auditor #1088
  • Query-tee #1089
• Operating Grafana Mimir #1009
  • Configuring Grafana Mimir to send traces #1090
  • Configuring high-availability deduplication #1091
  • Configuring shuffle sharding #1092
  • Configuring zone-aware replication #1114
  • Deploy monitoring mixin #1093
  • Encrypting data at rest #1094
  • Mirror requests to a second cluster #1095
  • Planning capacity #1096
  • Running Grafana Mimir on Kubernetes #1111
  • Securing communications with TLS #1097
  • Scaling ingesters up and down #1103
  • Updating or upgrading ingesters #1104
• Glossary #1102
• Reference: Configuration, including Configuration parameter lifecycle as a section rather than a separate file
• Reference: HTTP API

To be re-ordered

• guides/gossip-ring-getting-started.md #1108
• guides/sharded_ruler.md #1113

Add diagrams

• Add Mimir architecture overview diagram #1192
• Add Mimir read- and write-path diagrams #1194

Terminology cleanup

• Docs: Use the term component for ingester, distributor, or querier #1150
• https://github.com/grafana/mimir-squad/issues/547

[jdbaldry]

1. Propose high level topics to the Docs squad (e.g. Installing with Kubernetes, Overview of microservices, etc.)
2. Prioritize and order topics
3. Transform Cortex documentation into Mimir documentation
   • Ensure that references to chunks are removed
   • Ensure that project governance is replaced with Grafana governance
   • Vet API reference documentation and Docs: Refactor API documentation #734
   • Replace architecture diagram with something simpler. Possibly just re-use blocks storage architecture.
   • Write each article, and have it approved the by Docs squad.

[jdbaldry]

We have a number of operational tools in the repository (mimirtool, query-auditor, query-tee). Would a tools section make sense?

[osg-grafana]

We have a number of operational tools in the repository (mimirtool, query-auditor, query-tee). Would a tools section make sense?

Let's introduce those tools within the contexts that make sense, so that we remain goal-oriented.

[jdbaldry]

More areas for consideration. We have a bunch of technical components that are common to multiple services:

• Key-value store Docs: Describe key-value store component that is common to multiple services #1028
• Hash ring Docs: Describe the hash ring component that is common to multiple services #1029
  If we have concept pages for each of these, it would be useful to link to this from elsewhere.

Originally noted in #1017 (review)

[osg-grafana]

We have a number of operational tools in the repository (mimirtool, query-auditor, query-tee). Would a tools section make sense?

Let's introduce those tools within the contexts that make sense, so that we remain goal-oriented.

On second thought and for more easily distributing documentation work, I am creating a tools/ subdirectory to house these. See #1030

[osg-grafana]

@jdbaldry and @osg-grafana have closed this issue by either opening up subsequent (smaller) issues or marked completed work done.

[osg-grafana]

@grafana/mimir-maintainers and the @grafana/docs-squad, thank you all for incredible work. Superb all around!