Improve DSS operational documentation #1231
Description
Is your feature request related to a problem? Please describe.
The operational documentation, notably related to the deployment of a DSS instance, is hard to navigate.
Describe the solution you'd like
Format of the documentation
The documentation attempts to cover many use-cases and the usage of GitHub md files hosted on the repository appears to simply be not enough. Moreover this implies that the operational documentation necessarily follow the life-cycle of the code hosted on the repo, which oftentimes is not actually true.
Some fancier visual elements would be very useful, e.g. tabs for selecting alternatives, a menu giving overview of where we are at, visual elements to highlights notes and warnings, etc.
A dedicated documentation website with the proper tooling and with the content versioned through a git repository would be IMO the best approach and significantly improve user experience.
We could use:
- GitHub pages for hosting
- For generating pages based on markdown content from GitHub Actions:
- https://github.com/squidfunk/mkdocs-material (e.g. used by https://aws.github.io/copilot-cli/)
- https://gohugo.io/ (e.g. used by https://kubernetes.io/docs/home/)
Setting this up would be relatively low effort and IMO bring a big improvement in user experience of the documentation.
Structure of the documentation
Currently it appears that the documentation attempts to cover many different deployment scenarios:
- local / remote
- crdb / yugabyte
- minikube / gcp / aws
- helm / tanka
- single instance / pooling with other instances
Yet none of them appears to be clearly described as a set of self-contained steps as the documentation pages link to each other quite a bit, and often with exceptions as to what to follow on the other page.
IMO we'd benefit in:
- simplifying the supported scenarios (notably wrt dev deployment)
- clarifying the structure of the explicitly supported scenarios
A first draft could be:
- dev deployment: local with minikube, no pooling, 1 DSS instance with 1 DB node:
- helm or tanka
- crdb or yugabyte (or potentially even only yugabyte)
- operational deployment: remote on a cluster (aws or gcp), no pooling, 1 DSS instance with at least 3 DB nodes:
- helm or tanka
- crdb or yugabyte
- pooling existing instances on remote clusters (aws or gcp):
- helm or tanka
- crdb or yugabyte
This would exclude pooling from local dev instance, for which I'm not sure there is a use. But if there is, it may be easier to only support a deployment of e.g. 2 DSS instances pooled together locally in minikube.
Describe alternatives you've considered
- GitHub wiki: would be better than md files on the repo, but we'd miss still on a lot of things