Answering:
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.
1 Like
is OLM short for Operator Life Management?
Edit: AH I see ‘Operator Lifecycle Manager’
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”.
I can second your sentiment around this part. IMO, I as a user of a tool expect some official landing page(s) for each tool with a sort of… getting started. Perhaps the move for me will be, if I find a gap in the official page… try to pull up with a PR to whatever git repo backs that page?
Yes! OLM = Operator Lifecycle Manager.
I think about this page as the landing page for the docs, but I shouldn’t have to explain this: if users are not perceiving it this way, then it’s not ideal.
At the bottom of each page you will see:
And that’s the post backing that page.
Do we have an example of what you consider a project with excellent documentation structure and system? I am simple person and I would be happy with a simple Read the Docs, but I appreciate that doesn’t give a forum-like interface if someone wanted to start a conversation about the page (like the posts on Discourse).
@jamesbeedy showed me an example of a project he liked where there was EXACTLY ONE place to find All the docs.
Juju docs are scattered EVERYWHERE in multiple copies with unclear status in time.
The Android project came up as what we liked best in terms of structured LEARNING to develop classes of apps of various classes and common challenges.
Juju should copy that structure.
Like “Learn how to develop a machine charm”, “Learn how to develop a docker charm”, “Learn how to develop a Kubernetes charm”, “Learn how to port ansible to a juju charm”, “Learn how to develop a subordinate charm”, “Learn how to develop a charm with a database”, “Learn how to develop a charm with secrets/passwords”, “Learn how to develop with the operator framework” … and so on.
2 Likes
Do we have an example of what you consider a project with excellent documentation structure and system?
I think I can see now… we’ve got the docs page… which is pulling the data from the discourse posts? correct? So If I wanted to improve or change the docs then I need to post in discourse in a certain way?
I think right now, using Azure, shows docs backed by git… and PRs allowed to be formed in order to update/question the docs… or having an officialy way to have guides like Erik said… “Make a charm that relates a NodeJS app to MongoDB”
So officially if I want to do that… I should goto say
click the Help improve this document in the forum.
and actually edit the system post found at
Upgrade
?? or how do a propose additions…
Edit: I think now that I am reading the docs page and connecting with the discourse posts… it’s now clicking for me these two were connected… I think I search with google quite a bit and it seems to point me to discourse in some posts… the docs in another.
Agreed, I would like to present new concept as guides. I will think about a way to structure this transition; maybe we can work on some pages first and then see if people like it.
Precisely, Discourse is the backend, the repository. The exact markdown written on Discourse is then parsed into the docs pages.
You would have to have edit permissions for that specific post. You can add comments to it (and tag me) and I can review it and edit the original post.
If you would like to create a brand new doc, it’s just a matter of writing the Discourse posts, tagging it as a doc and then editing the navigation table above to get the docs page to render that Discourse post into a docs page. Does it make sense? Basically you will see a bunch of docs on Discourse because that’s effectively their repo.
The problem I see sometimes is that there are Discourse posts that are good docs and are not in juju.is/docs and that’s confusing.
2 Likes
here’s another example as I try to write another charm…
I am writing a relation between an HTTP type node… and NGINX … and I want to double check how to get the unit-get private-address type of info… for instance I know private-address is the ip address… but I want to check the port and see any other data I could pass from my HTTP server to NGINX… but when I goto search here in the website… unit-get returns nothing
I known personally that search is hard… but it makes me wonder if there is any comprehensive doc on these charm related pieces that I can find… and if I can’t find it through canonical’s own search function then how?
Edit: the saga continues when I found a man page… this was a good start until I do not see the private-address … so wondering if I’ve hit the wrong man page
at the bottom of this it says
“Please see the full documentation at http://juju.ubuntu.com/docs”
which instead of redirecting to the doc… directs to the new charm-hub store (I think it’s the new store…?)
Edit2: For kicks I tried this command at the juju level but… seems this juju version I found was super dated
$ juju unit-get <my_charms_name>
ERROR juju: "unit-get" is not a juju command. See "juju --help".
Did you mean:
budget
After seeking the juju help commands (which is very good, I must add) … I think I found something close… but it says public-address … i am guessing this is the same think?
$ juju show-unit <my_charms_name>/6
<my_charms_name>/6:
machine: "12"
opened-ports: []
public-address: 1.XX.XX.XX
charm: local:focal/<my_charm_name>-6
leader: true
edit3: I found a helpful command that I didn’t ever know about (although I think some ex-colleagues tried to tell me and I just don’t listen well… hah)
https://askubuntu.com/questions/983461/is-it-possible-to-check-the-open-ports-in-a-juju-charm
juju run --unit <my_charms_unit> -- <any_command_here> --formate=json
this helped me debug the correct statement and it turned out to be opened-ports
1 Like
Ouch, I wish your saga to find the command had ended at the search box. I will check with the web design team what’s going on. @jkfran, would that be something you would be able to help with?
CCing @bianka as I know she has been doing some work on the charmhub search box - maybe they share an engine?
I will ask someone to update that/add a bug, thanks for flagging it.
ironically… I still haven’t cracked it…
I can use that command from the CLI… but in my bash hook I gave up. I think we’re all on board with having a flourishing charm ecosystem… just takes me a minute to find what I need right now.
I forget if I mentioned previously but the Julialang docs have been QUITE organized and helpful…
https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/
I see the ad for a technical writer so I see efforts being put in place that’s awesome… just wanted to show some of the end-user POV on finding it all.
1 Like