docs: rewrite home page #2217
docs: rewrite home page #2217
Conversation
jahn-junior
commented
Mar 11, 2025
jahn-junior
commented
- Rewrite home page to comply with the standard homepage model.
- Fix outstanding lint errors in reference docs
docs/index.rst
Outdated
| :external+juju:ref:`Juju charms <charm>`. | ||
|
|
||
| When initializing a project, Charmcraft generates all the necessary files, pre-populated | ||
| with template content, which can be further catered to an application using Charmcraft's |
There was a problem hiding this comment.
| with template content, which can be further catered to an application using Charmcraft's | |
| with template content, which can be further catered to a web app using Charmcraft's |
There was a problem hiding this comment.
Gonna have to ask for a reversion here - the current extensions handle several types of web apps, but Charmcraft as a whole is more general. A quick example is that Charmcraft also helps charm databases.
There was a problem hiding this comment.
Maybe "a service" or something like that would be more appropriate?
There was a problem hiding this comment.
"services" fits the mould, in my view, but I believe @tmihoc had some better alternatives?
There was a problem hiding this comment.
I changed it to services for the time being, but am open to any other terms that might be more consistent with the Juju documentation.
docs/index.rst
Outdated
| For those looking to add their applications to a Juju deployment, Charmcraft will prove | ||
| to be an invaluable tool. |
There was a problem hiding this comment.
Any suggestions for the final paragraph? This was included as more of a placeholder.
The standard model states that this should state who the product is useful for, but I was having a hard time coming up with anything besides "charm authors".
There was a problem hiding this comment.
If you need a good example, I think the Landscape docs put it very solidly.
I think part of the solution could be to borrow the second-half of the last sentence from the previous paragraph and combine it with this one.
There was a problem hiding this comment.
Well, Charmcraft is in fact only for charm authors. You could reword it in a way that basically says the same thing but you'd probably end up redefining the word "charm", and that feels inappropriate at this stage. (https://juju.is/docs > the intro line at the very top defines Juju and charms already, and from there onwards we just embrace the words.)
There was a problem hiding this comment.
@tmihoc @medubelko I did a rewrite and I'd be curious to hear your thoughts on it. I tried to add a bit more context without needlessly restating what has already been defined in the Juju docs. I felt it necessary for this to say more than "Charmcraft is for charm authors", as in my mind that amounts to the same as saying "cars are for drivers". With that being said, it can always be improved, so I'm open to any and all feedback you may have!
There was a problem hiding this comment.
Tremendous thanks for putting this together, @jahn-junior! I think it's shaping up closer to what the model needs.
My review is non-blocking, but there's one grammar fix in it. Thanks!
docs/index.rst
Outdated
| state-of-the-art results in record time. | ||
|
|
||
| If you're a charm author, you *must* use Charmcraft! | ||
| Charmcraft is the official command-line tool for initializing, packaging, and publishing |
There was a problem hiding this comment.
official
I may have mentioned this in the original doc, but what do you think about "the command-line tool"? "official" stands out to me.
There was a problem hiding this comment.
Agreed. I think I actually had it that way initially, but changed it after taking one of your comments on the google draft too literally. My mistake!
docs/index.rst
Outdated
| When initializing a project, Charmcraft generates all the necessary files, pre-populated | ||
| with template content, which can be further catered to a web application using | ||
| Charmcraft's array of extensions. Packing a charm is similarly streamlined, as | ||
| Charmcraft automatically fetches project dependencies and compile any modules before |
There was a problem hiding this comment.
| Charmcraft automatically fetches project dependencies and compile any modules before | |
| Charmcraft automatically fetches project dependencies and compiles any modules before |
There was a problem hiding this comment.
Oops, I overlooked this when I updated the first part of the sentence from "will automatically fetch" to "automatically fetches".
docs/index.rst
Outdated
| with template content, which can be further catered to a web application using | ||
| Charmcraft's array of extensions. Packing a charm is similarly streamlined, as |
There was a problem hiding this comment.
| with template content, which can be further catered to a web application using | |
| Charmcraft's array of extensions. Packing a charm is similarly streamlined, as | |
| with template content, which can be further catered to a web application. | |
| Packing a charm is similarly streamlined, as |
Working on a web app is a great story to tell! I don't know that new readers will understand what "extension" means in the introduction. My sense is that it's too early to mention them.
There was a problem hiding this comment.
I think it's slightly better after the latest commit. I agree that the bit about extensions was a bit forced, so I took it out of that first section? Do we think that they should be worked in somewhere else or is it too far outside of the core story to include here?
docs/index.rst
Outdated
| Charmcraft's array of extensions. Packing a charm is similarly streamlined, as | ||
| Charmcraft automatically fetches project dependencies and compile any modules before | ||
| producing the final charm artifact. When it comes time to publish a charm on | ||
| `Charmhub`_, Charmcraft provides tools for charm authors to register a charm's name, |
There was a problem hiding this comment.
What do you think about "register a charm" as a user story? Is it "charm name" to avoid the confusion about individual charm artifacts vs. the charm as a whole?
For comparison, we use "register a snap" and "register a source" in Snapcraft and other tools.
There was a problem hiding this comment.
I prefer "register a charm" for consistency - the specific .charm file that gets packed is equivalent to a specific .snap file, so we should be encouraging use of the term "revision" for it.
There was a problem hiding this comment.
@lengau +1 for "register". That said, to me it feels like a detail of publish so I wouldn't personally highlight it on the homepage.
docs/index.rst
Outdated
| Charmcraft simplifies every step of the charming process, enabling charm authors to | ||
| bypass boilerplate steps and focus on the contents of their charms. Additionally, | ||
| Charmcraft's integration with tools such as :external+ops:doc:`Ops <index>` and Charmhub | ||
| provides charm authors with a truly comprehensive toolkit for charm development. |
There was a problem hiding this comment.
| provides charm authors with a truly comprehensive toolkit for charm development. | |
| provides charm authors with a comprehensive toolkit for charm development. |
There was a problem hiding this comment.
"Charmcraft simplifies every step of the charming process" >> I think this is the part to emphasize here. Charmcraft takes care of all of initi, pack, and publish, and the Ops templates it provides also help with development and testing.
"Charmcraft's integration with tools such as Ops and Charmhub provides charm authors with a comprehensive tool..." >> First, just like Charmhub, Ops should be mentioned in the previous paragraph -- Ops code is part of the template content that charmcraft init provides. Second, the sentence as a whole sounds odd -- I mean, Charmcraft together with Ops amount to a comprehensive SDK, but Charmhub is hardly part of a "toolkit", and I wouldn't say that it's the integration that provides a comprehensive SDK -- I'd rephrase it to something else.
There was a problem hiding this comment.
Thanks for pointing these things out! These are factors that I likely wouldn't have considered if I didn't get another set of eyes on the PR.
I agree on both points. I included a mention of the YAML and Ops template content where I bring up initialization. I also reworded that last sentence in the third paragraph. I think "charm development experience" is more accurate than "toolkit", as I would consider publishing, which Charmhub is an integral part of, to be one of the final steps in development. Please let me know what you think about the change!
docs/index.rst
Outdated
| For those looking to add their applications to a Juju deployment, Charmcraft will prove | ||
| to be an invaluable tool. |
There was a problem hiding this comment.
If you need a good example, I think the Landscape docs put it very solidly.
I think part of the solution could be to borrow the second-half of the last sentence from the previous paragraph and combine it with this one.
docs/index.rst
Outdated
| :external+juju:ref:`Juju charms <charm>`. | ||
|
|
||
| When initializing a project, Charmcraft generates all the necessary files, pre-populated | ||
| with template content, which can be further catered to a web application using |
There was a problem hiding this comment.
I'm finding "can be further catered" a little bit awkward -- I think I'd say "targeted" or something like that, but I'll defer to everyone else's native speaker ear here. More importantly, I think the relevant bit there is to highlight "kinds of web applications" or "classes...", but @erinecon would know better.
There was a problem hiding this comment.
I feel like "catered" sounds fine to my ear, but "targeted" also makes sense as that's basically what the extensions do. I have no strong preference and leave it up to @jahn-junior :) Upon a second read-through, I think we should be more explicit that's it a specific set of wep apps and not just any random web app. Below is a suggestion (probably the linter will hate it, sorry about that):
| with template content, which can be further catered to a web application using | |
| with template content, which can be further catered to certain types of web apps (Django, FastAPI, Flask, Go) using |
There was a problem hiding this comment.
In the original, the second paragraph mentioned Ops, Charmhub, Python, YAML, Django, FastAPI, Flask, Go on purpose. I'm not sure why they were removed -- imo they're all either directly relevant to the story (part of the template content generated on charmcraft init is Ops code, so Ops should be mentioned there; similarly, YAML and Python give people a quick tanngible sense of what a charm is) or useful buzzwords (e.g., a reader who is familiar with Django, FastAPI, Flask, or Go will quickly care if they see those words).
docs/index.rst
Outdated
| For those looking to add their applications to a Juju deployment, Charmcraft will prove | ||
| to be an invaluable tool. |
There was a problem hiding this comment.
Well, Charmcraft is in fact only for charm authors. You could reword it in a way that basically says the same thing but you'd probably end up redefining the word "charm", and that feels inappropriate at this stage. (https://juju.is/docs > the intro line at the very top defines Juju and charms already, and from there onwards we just embrace the words.)
docs/index.rst
Outdated
| Charmcraft's array of extensions. Packing a charm is similarly streamlined, as | ||
| Charmcraft automatically fetches project dependencies and compile any modules before | ||
| producing the final charm artifact. When it comes time to publish a charm on | ||
| `Charmhub`_, Charmcraft provides tools for charm authors to register a charm's name, |
There was a problem hiding this comment.
@lengau +1 for "register". That said, to me it feels like a detail of publish so I wouldn't personally highlight it on the homepage.
There was a problem hiding this comment.
I wouldn't invest any effort in this file -- this doc is generated automatically from charmcraft.yaml upon charmcraft.pack (@lengau please correct me if I'm wrong), so I'd replace the contents of that doc with just a note to that effect.
There was a problem hiding this comment.
I only bothered with the line lengths so that I wouldn't see the warnings when running the linters.
