As a CTO
I want to have a first impression in less than 30 minutes
So that I can evaluate Syn
The current "Getting Started Guide" (https://docs.syn.tools/syn/tutorials/getting-started.html) is big read and takes very long to do. There's no clear target audience: Is it meant for developers so they can start contributing or is it meant for someone who just wants to try out in action without understanding the behind-the-scenes and possibly buy commercial support for it?
The title "Getting Started" is already misleading. With a "Getting started" title my expectations are set to a point where I can setup something quick and easy. I'm not bothered about understanding the architecture, there can be links for further topics in the guide.
That being said, the setup should be as automated as much as possible. The best possible option, IMO, is like K3s does it:
curl -sfL https://get.syn.tools | bash -
This script checks if all pre-requirements are met and covers all of the installation: to get a control cluster up and synfecting the compute cluster, all locally.
The remaining content of the tutorial should be usage-focused:
Where to find the catalogs and components
How to make changes to the cluster or tenant, roll them out, verify the change (understanding the hierarchy of the configuration)
See the applications in ArgoCD
The first impression of the current guide is rather devastating from my own experience: It's very complex, has high entry requirements, requires 18 "easy" steps to install something.
There should still be second guide that explains the internals and architecture. So maybe creating the install script and providing a completely new guide while renaming the current one is the way to go.
Alternatives
Rename the guide. Better titles for the current guide are:
Context
As a CTO I want to have a first impression in less than 30 minutes So that I can evaluate Syn
The current "Getting Started Guide" (https://docs.syn.tools/syn/tutorials/getting-started.html) is big read and takes very long to do. There's no clear target audience: Is it meant for developers so they can start contributing or is it meant for someone who just wants to try out in action without understanding the behind-the-scenes and possibly buy commercial support for it?
The title "Getting Started" is already misleading. With a "Getting started" title my expectations are set to a point where I can setup something quick and easy. I'm not bothered about understanding the architecture, there can be links for further topics in the guide.
That being said, the setup should be as automated as much as possible. The best possible option, IMO, is like K3s does it:
This script checks if all pre-requirements are met and covers all of the installation: to get a control cluster up and synfecting the compute cluster, all locally.
The remaining content of the tutorial should be usage-focused:
The first impression of the current guide is rather devastating from my own experience: It's very complex, has high entry requirements, requires 18 "easy" steps to install something.
There should still be second guide that explains the internals and architecture. So maybe creating the install script and providing a completely new guide while renaming the current one is the way to go.
Alternatives
Rename the guide. Better titles for the current guide are: