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