bacongobbler
commented
2 years ago I've been looking at other documentation guides, and they choose to handle this by making their documentation oriented towards the user, such that their quick start guides are all about how to install and use the client. Then they have a separate section in their docs that discusses how to deploy the server-side infrastructure and how to maintain it.
e.g.
https://kubernetes.io/docs/home/ https://www.nomadproject.io/docs https://docs.docker.com/
This seems like a good approach for Hippo as well. I will change the introductory pages to reference using the Hippo CLI, moving the "set up hippo server" guides elsewhere.
Eventually I'd like to split the docs into two groups: users and administrators.
Administrators are the individuals who maintain the infrastructure necessary to host applications. They are the ones installing, upgrading, and maintaining their own instance of hippo-server. They may also be responsible for administrative tasks like registering new accounts or writing new "helper tools" using the API as a reference guide. They want to know how to upgrade hippo-server, how to query the database, domain/TLS configuration, and how hippo-server communicates with nomad. They may also want to know how to handle Disaster Recovery (DR) scenarios.
Users are individuals who interact with the Hippo CLI. They are the ones creating applications, setting up release channels, inviting members to collaborate on an application, uploading apps to bindle, etc. They want to know what a HIPPOFACTS file does, how to register an account, create an application, and upload their source code. They may also want to know how to ensure other users cannot see their apps, or how to add other users to collaborate on their app. They may also want to know how to set up snapshots or advanced release channel configuration.
Right now the quickstart documentation tried to cover both bases by asking the user to install hippo, boot hippo-server, and create an app. I'd like to make that focused purely on the "User", and move the "boot hippo-server" guide to a separate section of the documentation.