Changes to charmhub.io pages

[Lukewh (Luke Wesley-Holley)]

Tl;dr – If you do not have the docs element set in your metadata.yaml or bundle.yaml your GitHub README.md will no longer be the default content displayed for your charm and bundle pages. The description from the metadata.yaml or bundle.yaml will be used instead, so make sure they’re up-to-date and useful. The switch will happen happened on Thursday 20th April.

The Description tab is the homepage of your charm or bundle and is, generally, the first page a user will see. As such, it’s important that the page targets the correct audience.

Current experience and functionality

If your metadata.yaml or bundle.yaml does not contain a docs element that points to an appropriate discourse topic, we parse and display the README.md from the charm/bundle repository. This is not ideal as the README.md is, and should be, targeted towards developers to convey technical information and implementation details. This is less ideal for end users who want to learn about the charm/bundle, and explore both high-level concepts and the value proposition.

Target experience and functionality

Canonical has a “Standard documentation home page structure” (screenshot above) that has been designed as a generic landing page for documentation that caters for many users, and it provides common and consistent structure to documentation throughout Canonical products. It’s not expected that all charms and bundles will have Tutorials, How-to guides and a list of Project and community links, however it is expected that all charms and bundles contain at least the following:

• Summary – A single sentence that says what the charm/bundle is, succinctly and memorably.
• Description – A paragraph of one to three short sentences, that describe what the charm/bundle does.
• Needs – A paragraph of similar length, explaining what need the charm/bundle meets.
• Target – A paragraph that describes whom the charm/bundle is useful for.

We will be striving for charms and bundles to adopt this structure for the “Description” tab moving forward.

With the removal of GitHub README.md we will instead show the charm/bundles description element from the metadata.yaml or bundle.yaml file. If the docs element is provided, and links to a valid discourse topic, we will display the topic contents only.

Summary of required changes

Provisional date of change: 20th April 2023

Update metadata.yaml or bundle.yaml:

• description element. This field does not support markdown, but you can provide multiple lines and paragraphs to cover the points above (Summary, Description, Needs, and Target).
• source element. This field can be used to direct the curious to the source-code and originally displayed README.md.

Optionally create a discourse topic: Follow the How to add docs to your charm page on Charmhub guide to implement the “Standard documentation home page structure”, knowing that the contents of this topic will replace the content of the description element from the metadata.yaml or bundle.yaml.

We’re giving a few weeks notice as there may be questions and concerns that need addressing, please leave your feedback and ask questions .

[jdkandersson (David Andersson)]

Thanks for the post Luke.

I’m trying to understand it. Currently, even if a docs key is provided, the readme.md content is displayed on the landing page of the charm documentation on charmhub. Is that changing as well, or is that staying the same?

For example, for the Indico charm, this is the metadata.yaml: https://github.com/canonical/indico-operator/blob/main/metadata.yaml which includes the docs key pointing to this topic: Indico Documentation Overview - charm - Charmhub. The default landing page on charmhub (Charmhub | Deploy Indico using Charmhub - The Open Operator Collection) shows the content from the readme: https://github.com/canonical/indico-operator/blob/main/README.md

[jnsgruk (Jon Seager)]

So with this change, the index page of you Discourse docs would be displayed by default, not the README.

We’re moving to never displaying the README, as it’s very hard to write a README that makes sense on Github and on Charmhub

It boils down to:

• By default, just display summary and description in metadata.yaml
• If docs: is present, display the index topic by default on the charm page

[jdkandersson (David Andersson)]

Thanks @jnsgruk I assume things like the navigation table will be stripped out? So the content for Indico as it stands would be something like:

Indico is an open-source tool for event organisation, archival and collaboration, catering to lectures, meetings, workshops and conferences.

For details on Indico’s features, see [this page](https://getindico.io/features/).

And we essentially need to copy the content from the readme into the index page above the navigation table and then nothing on the documentation should change?

I would also recommend we communicate the change for when the docs key is present specifically more broadly since for most of our charms in IS DevOps, for example, the index topic on discourse contains relatively meaningless content, similar to Indico. It is easy to update, it just wasn’t clear from the original post (at least to me) that we would need to.

It is a good change that we are making, it is better than pulling some content from readme and other from discourse

[jnsgruk (Jon Seager)]

@jdkandersson

I assume things like the navigation table will be stripped out?

If the docs index has a nav, it will be rendered properly on the left hand side still, as seen below:

@jdkandersson

And we essentially need to copy the content from the readme into the index page above the navigation table and then nothing on the documentation should change?

I’d argue that this is the wrong approach. The reason we’re making this change is that often READMEs from the source repo are not great documentation, or at least not in the “consumer” sense, anyway. If the Indico README happens to be a great front page for the Charm on Charmhub, then go for it, but I don’t think that it should be the rule.

@jdkandersson

It is a good change that we are making, it is better than pulling some content from readme and other from discourse

Indeed - the purpose really is to allow devs to have a great README for other developers, but also a great landing page in the charm catalogue that is Charmhub. I think it’s a change for the better

My understanding is that we’ll also be landing support for URL fields in metadata such as issue tracker, homepage, source code, etc. @Lukewh will be able to confirm exactly which fields.

[jdkandersson (David Andersson)]

@jnsgruk

I’d argue that this is the wrong approach. The reason we’re making this change is that often READMEs from the source repo are not great documentation, or at least not in the “consumer” sense, anyway. If the Indico README happens to be a great front page for the Charm on Charmhub, then go for it, but I don’t think that it should be the rule.

Yes I agree, in our team we have put quite a bit of effort into the docs and our READMEs are designed for the charmhub documentation rather than for the GitHub repo. I should have been clearer on that