So my thinking was to have the docs divided in two: OLM and SDK.
OLM would mimic the use flow of Juju: bootstrap, deploy, relate. The SDK (credits to @jnsgruk ) would start with an example charm and then dive into the specifics.
The way the documentation system works is the following:
- A post in Discourse gets parsed into juju.is/docs as a docs page.
- The index you see on the left side is defined by the navigation table here: The Charmed Operator Lifecycle Manager
- If a Discourse post is not listed in the navigation table, it can not turn into a docs page. It’s how the system works.
Now, I also feel a bit uneasy with the idea of having good documentation in Discourse posts (and not juju.is/docs) because it felt a bit less “official”. The dynamics of sending users from the website to the forum to get information makes me (as a user) feel like I am doing something too complex (so complex that the standard documentation doesn’t cover it and I will have to go to the forum to get help).
Does it make sense?
What’s your feeling on this? Maybe we can improve the process somehow.