Reorganize deployment/operations docs

[slinkydeveloper]

Right now we have these info scattered a bit through the doc, without any clear understanding of the flow for which the user goes through these pages.

[slinkydeveloper]

My idea would be the following:

• We start with a "local dev experience page", where we describe all you need for local dev experience/local dev loop: start the runtime container image with the correct flags, start the service, discover the service (relevant point here). This page should be very much opinionated, without "alternatives" to do the same things, and should cover the whole local dev loop Code -> Deploy local -> Test -> Repeat, e.g. including what should you do after you modifying the code?
• From the local dev experience page, in the "next steps" we link to the following pages:
  • Deploying Restate
  • Deploying and operating services

The deploying Restate page looks as follows:

• Describe deployment suggested setups
• In the "next steps", perhaps link to configuration page and other relevant pages for deployment (maybe observability?)

The deploying and operating services page looks like this:

• (Intro) Services and Service endpoints
• Deployment
  • Knative (Deploy using Knative #62)
  • Lambda
  • Kube standalone
• Registration
  • Public and private services (Public and private services restate#585)
• Upgrade (Versioning documentation #61)
• Removal (Allow to delete an endpoint restate#586)

[slinkydeveloper]

While the first "local devex" page should be written for the wider audience possible, the other two pages should be a bit more detailed, as IMO you land on those after you tried Restate, you liked it, and you wanna see if it can easily fit your infra/deployment flows.

[tillrohrmann]

Thanks for creating this proposal @slinkydeveloper. It makes a lot of sense to me to add more details for how to deploy services and also how to manage them (registration & upgrade). What you've proposed (local devex page + dedicated pages for different deployments of services + deployment of Restate runtime as a separate section) sounds reasonable to me. Also the set of deployment options makes sense. Maybe I would put Lambda first.

Curious to hear what @gvdongen thinks and whether this fits into the documentation effort as it is currently planned/envisioned.

[gvdongen]

Thanks @slinkydeveloper for the brainstorming! I like where this is going and I think it sounds reasonable for the deployment/operation part. But I would like to take this along is a larger review of the structure of the docs. For example, I think the local dev experience docs is partly covered by the getting started. I also think we are currently missing some sections. And almost everything is now under deployment/operations. Maybe we should think a bit about how to restructure this.... I will take the time next week to think about which sections we need and what goes where...

[gvdongen]

A proposal of how to do the restructuring for the entire docs (taking along what was written here): https://docs.google.com/document/d/1wCdSNfmjvyxxA_7bN5HU3DWetKHcTPVwoCmEnF_MGXQ/edit

[tillrohrmann]

Thanks for drafting the proposal for the documentation outline @gvdongen. It looks good to me. It also covers the aspects that @slinkydeveloper wanted to change (having a dedicated service section which covers deployment, registration, upgrade & removal of services). So +1 for this proposal.

[slinkydeveloper]

+1 for me as well

[gvdongen]

Fixed by #95