Documentation improvements #156
Description
Problem
SealCI's architecture documentation exists at least for each components (not as a whole), but it is hidden and non-navigable. It also lacks a lot of features of proper documentations.
Solution
I think a static, content-driven website (such as one generated by Rust's mdbook, or mkdocs, or similar...) is necessary to organize our documentation and make it readable (so that users/... can navigate it, find their way through it). mdbook has a search feature, I think this is a good requirement for a docs site.
We also need Getting started and About pages, to get users to easily try and make themselves an idea of what sealci is.
Building on that, SealCI has features other products don't (such as sealcid, its own VMM, its own release agent component, all components being self-hostable, not just the runners; it's all under an Apachev2 License...). It also has a UI, etc. => We need a table comparing SealCI to other similar products.
We also need a presentation/diagram of the (deployment) architecture of SealCI - for operators that have to manage the networks and processes, and for potential contributors. This can appear in the "Architecture" page. This page should also feature the reasons for such architecture decisions (problems it solves, why it's a separate component, etc - why it was made that way).
A Goals page is probably also a good idea, for us to organize and for users to know if a feature, fix or architecture change is coming before they ask for it.
Finally, the GitHub README needs to be updated to reflect that. Particularily, there is currently only one line about SealCI, and the rest is an indigestible dependencies SBOM (who had this awful idea?? Oh.) and short arch docs. Our docs/arch/ folder is both hidden, and non-navigable.
Summary of suggested solution:
- Static, content-driven website for easy to navigate documentation.
- Getting started chapter for users to run and test SealCI fast and easy.
- Documentation chapter "About" SealCI
- Documentation chapters for Architecture as a whole and per-component.
- Documentation chapters specific to users, operators, contributors.
- Documentation chapter for goals/objectives/next steps.
- README update. => It's the first thing people see.
Later down the line, I think we may need:
- Contributor guide
=> We should take inspiration from existing, well-written documentations, as well as understand best practices and principles that can be found in various adaptable documentation frameworks (our current what/why/how, Diátaxis, etc)
Feel free to comment on this first draft., find more resources, link good documentations or frameworks down below - etc.