Sort how-to listing in our docs -- alphabetical?

[james-garner-canonical]

The ordering of the how-to items in our docs is non-obvious to me, which I noticed when trying to find specific pages in the sidebar today.

There are a lot of Manage X items, which would scan a lot easier if they were alphabetised. Alphabetical order would probably be nice overall. This would have the benefit of putting Get started with ... items first in the list currently.

Minor thing to fix at the same time: The titles in the side bar and index page for these two items are kinda ugly -- I guess the hyphen is being automatically stripped out? Maybe we should use (machine) and (kubernetes) instead.

• Run workloads with a charm machines
• Run workloads with a charm Kubernetes

@dwilding and I thought that an issue would be a good place to record any discussion and decision on this.

@tmihoc, the Juju user and contributor listings also seem non-obviously ordered. Thoughts?

[dwilding]

Thanks for creating this.

I agree we need to have an approach to the order. I vote for alphabetical order in the sidebar, with the in-page listing bumping particularly important pages to the top. For example, look at Pebble Reference:

• In the sidebar, the child pages are listed in alphabetical order
• On the Reference page itself, we put Layers, Pebble commands, and Service failures first - for better discoverability

For the "Run workloads..." pages, how about "Run workloads with a machine charm" and "Run workloads with a Kubernetes charm"?

[james-garner-canonical]

with the in-page listing bumping particularly important pages to the top

Agreed that this is good, and easy to follow thanks to the sections

For the "Run workloads..." pages, how about "Run workloads with a machine charm" and "Run workloads with a Kubernetes charm"?

Sounds good to me.

[tonyandrewmeyer]

The ordering of the how-to items in our docs is non-obvious to me, which I noticed when trying to find specific pages in the sidebar today.

The order is intended to be the order of things you do when you're developing your charm. First up is logging because it's universal - but the plan (I think I mentioned in another PR) is to have a "How to manage charms" first up that would absorb that. The next thing you're probably going to work on is the workload. As you do that, you probably need to figure out storage and resources if you're using those. Then you work on the charm UX, actions and config. Then you connect the charm with relations.

It's a bit fuzzy after that, but ends with nice-to-haves like versions, and then the very odd-one-out of converting an old charm. Testing is at the end and probably people are writing tests at the end, but when we get the new how-to for testing I would argue for it go to much earlier, because ideally people are writing tests earlier.

The other thing is if you look at ours:

And then at Juju:

There are quite a few different items, but the common ones are in the same order. And then at charmcraft:

Again, a lot of items not in common, but the ones that are are again generally in the same order. Not an accident!

There are a lot of Manage X items, which would scan a lot easier if they were alphabetised. Alphabetical order would probably be nice overall. This would have the benefit of putting Get started with ... items first in the list currently.

If you're going to argue for alphabetical, then I don't think you can argue that specific items come first for other reasons :). Otherwise you're saying something like "alphabetical but no new items with a first letter before g" 😉.

Minor thing to fix at the same time: The titles in the side bar and index page for these two items are kinda ugly -- I guess the hyphen is being automatically stripped out? Maybe we should use (machine) and (kubernetes) instead.

Ah yes, this was on @tmihoc's list to fix I think - we spotted it when working on the docs a week or so ago, but it might have fallen off. If you know how to fix it then a PR would be good - even one that parenthesises would be ok I think.

[dwilding]

The order is intended to be the order of things you do when you're developing your charm.

This does make sense, but I feel that the sidebar ordering isn't a great way to signal our intention. I would still vote for alphabetical with the page contents showing the order of things to do (with the possibility of adding text to make things more explicit).

[james-garner-canonical]

The order is intended to be the order of things you do when you're developing your charm.

Imho this type of ordering is good for an explicitly ordered series like a tutorial, but less so for a large collection of how-tos, especially as beginners, who probably need the how-tos the most, may find the ordering non-obvious.

If we do want to stick with a natural/logical ordering so that it's easier for people that know their way around charm development to find things, then perhaps we should look at grouping them under some sections. "Getting started with charms", "Managing workloads", "Charm UX", "Integrating charms", for example. I think this would be great for the index page, like the Pebble reference.

Since there will probably be a number of things that don't easily fit into a category, and since the categories would collapse in the sidebar, making it harder to find things at a glance, I think alphabetical would work better there.

If you're going to argue for alphabetical, then I don't think you can argue that specific items come first for other reasons

Haha good point, arbitrary sorting could put those items first anyway. And of course there's no reason that "Getting started with X" should logically come before "Manage Y". I do think that if we had a lot of "Getting started with X" which would all came after "Manage X" when sorted alphabetically, then that would be a clear negative to sorting that way though.

[tmihoc]

What @tonyandrewmeyer said. Plus keep in mind we'll want to touch up the landing pages in all cases (Juju, Charmcraft, Ops) and group the titles in some logical fashion, and the order we have is the basis for that grouping.

Alternatively, we can have titles alphabetically in the side navigation but grouped logically on the landing page. It's what we'll end up doing for reference anyway once we start working on the landing pages objective that Daniele has for all projects at Canonical. However, imo there's a conceptual difference between how-to guides and reference where the alphabetical order makes more sense for the reference than the how-tos.

[dwilding]

If we group the pages into sub-categories so that there are fewer pages in each list, I'm less concerned about the lists being non-alphabetical.

@tonyandrewmeyer I get your logic about "Manage logs", but to me this one really looks like a mistake. As a small interim step, would you be OK with moving it immediately above "Manage storage"?