As of today (17.8.2022) the Syn documentation is quite a mess IMO.
As a component and package author the relevant pages are stretched out in various places. Some examples:
The Tutorial to write components contains the whole Syn setup including local Lieutenant. However, currently at VSHN we nowadays develop components with local compilation without cluster deployments. Yet the tutorial for writing packages is in the Commodore Antora project. :exploding_head:
All the commodore component best practices are under the root Syn Antora project, not in Commodore. Yet when developing components, the main interaction happens within the Commodore tooling.
The tutorial for Packages doesn't explain how a package is intended to be used. There is no reference page or explanation, but only a small section in a simplistic tutorial
The "Creating a package" section in the package tutorial doesn't refer to the best practices, yet they belong together. That means, as a package author that wants to test packages also locally, I need to keep open at least 3 tabs with separate documentation locations.
(This list is incomplete, might be extended)
On some locations I question Divio's structure to put random articles into the 4 categories (Tutorial, How-to, Reference, Explanation). Or at least it's badly done as of today.
For example, in the following Screenshot the menu structure doesn't make sense:
Under How-to guides, why are there top-level random articles, but submenus for Lieutenant Operator and API, and an empty Steward entry that isn't even clickable.
Under Explanation same thing, seemingly random articles and then inclusion of completely different tools.
Over the years, it seems people can't make a clear distinction between a tutorial and a how-to, or an explanation and reference page. Often there are parameters and patterns explained in a how-to or tutorial page, but there's nothing in the references.
how-to guides and technical reference are both what we need when we are at work, coding
Yet when I code, the stuff I need is either a Tutorial or in a completely different Antora project xD
Alternatives
Most of the documentation is aimed towards engineers. Yet there are different kinds of engineers:
Component or package authors that need to learn how to write good jsonnet and parameter structures.
Cluster-admins that install components and packages
Component or package maintainers/owners that review PRs and release new versions
CTOs that want to learn what project syn is and does to evaluate whether this is something for them.
Maybe an alternative structure that is aimed towards the different personas is more helpful than strictly dividing into the 4 divio categories. Maybe it's still sensible to keep the nature of a page as a Tutorial, how-to, explanation or reference, but only change the menu/nav links to them. Some personas require the same pages, for example both cluster-admins and package authors need to know how to set parameters so their package or component gets installed.
Prose example (just an idea worth discussing):
For Component Contributors:
- Tutorial: Bootstrap new component
- How-To: Jsonnet problems and patterns
- How to: Running Commodore
- Reference: Style Guide
- Reference: Renovate version pins
For Component Maintainers:
- How to Release a component
- How-to: Prepare for modulesync(/cruft)
- How to: Running Commodore
- Reference: Review Guide
- Reference: Style Guide
- Reference: Renovate version pins
For Cluster-Administrators:
- How to: Compile a Cluster catalog
- How to: Change a parameter
- How to: Running Commodore
For new users:
- Tutorial: Getting started
- Reference: Concepts
The goal is the each persona basically has everything relevant for a certain task. A component author doesn't care about compiling catalogs at the time of authoring a PR. However, the same person might switch the persona to a cluster-admin when they try to actually deploy their component to a cluster, then the relevant documentation pages change.
Developing Lieutenant is a completely different topic and should be rather standalone than randomly put somewhere.
Context
As of today (17.8.2022) the Syn documentation is quite a mess IMO.
As a component and package author the relevant pages are stretched out in various places. Some examples:
(This list is incomplete, might be extended)
On some locations I question Divio's structure to put random articles into the 4 categories (Tutorial, How-to, Reference, Explanation). Or at least it's badly done as of today. For example, in the following Screenshot the menu structure doesn't make sense:
How-to guides, why are there top-level random articles, but submenus for Lieutenant Operator and API, and an emptyStewardentry that isn't even clickable.Explanationsame thing, seemingly random articles and then inclusion of completely different tools.Over the years, it seems people can't make a clear distinction between a tutorial and a how-to, or an explanation and reference page. Often there are parameters and patterns explained in a how-to or tutorial page, but there's nothing in the references.
As Divio puts it: (https://documentation.divio.com/structure/#why-isn-t-this-obvious)
Yet when I code, the stuff I need is either a Tutorial or in a completely different Antora project xD
Alternatives
Most of the documentation is aimed towards engineers. Yet there are different kinds of engineers:
Maybe an alternative structure that is aimed towards the different personas is more helpful than strictly dividing into the 4 divio categories. Maybe it's still sensible to keep the nature of a page as a Tutorial, how-to, explanation or reference, but only change the menu/nav links to them. Some personas require the same pages, for example both cluster-admins and package authors need to know how to set parameters so their package or component gets installed.
Prose example (just an idea worth discussing):
The goal is the each persona basically has everything relevant for a certain task. A component author doesn't care about compiling catalogs at the time of authoring a PR. However, the same person might switch the persona to a cluster-admin when they try to actually deploy their component to a cluster, then the relevant documentation pages change.
Developing Lieutenant is a completely different topic and should be rather standalone than randomly put somewhere.