Sort Table of Contents

[zoffixznet]

As reported in Raku/user-experience#10, the method names in the table of contents are in no coherent order, which makes it hard to spot the one you want to read about. I'd suggest them to be sorted alphabetically.

[AlexDaniel]

Are you saying that ｢combinations｣ and ｢permutations｣ should be far away from each other? I don't think so. In fact, I always loved how it was more or less sorted in “what I need is usually on top” order.

[tbrowder]

Then maybe there ought to be clear category subparts under which such things could be grouped. Closing this without more discussion isn't helpful IMHO.

[Skarsnik]

Yep. For me an example of a good documentation is Qt. it's alphabetical
order but methods that do thing related thing are mentioned in each other.

2016-02-11 13:49 GMT+01:00 Tom Browder notifications@github.com:

Then maybe there ought to be clear category subparts under which such
things could be grouped. Closing this without more discussion isn't helpful
IMHO.

—
Reply to this email directly or view it on GitHub
#392 (comment).

Sylvain "Skarsnik" Colinet

Victory was near but the power of the ring couldn't be undone

[zoffixznet]

@tbrowder would you have any examples of how such a category layout would look like?

In the screenshot above, I see keys, values, and kv as one group, pairs is somewhat similar to kv, but doesn't really fit into that group entirely. To me classify more tightly fits into a group with sort, but you can equally argue the grep group is appropriate too.

There is some intelligence with the current grouping; trying to break it up into more refined subcategories would result in a lot of bikeshed IMO, especially since many methods are inherited from other classes.

Also, does anyone know how the current sorting is made up? It is all just hand-ordered?

[tbrowder]

On Thursday, February 11, 2016, Skarsnik notifications@github.com wrote:

Yep. For me an example of a good documentation is Qt. it's alphabetical
order but methods that do thing related thing are mentioned in each other.

Sounds like a good solution to me (maybe a bit of pain for doc writers, but
only for a brief while).

-Tom

[AlexDaniel]

Yeah, closing this is not helpful. If somebody feels uncomfortable with the current layout then we should do something.

There are other interesting ways to tackle this. For example, we can add a javascript _A-Z_ button that will sort the list alphabetically.

[coke]

Managing a category layout is more work that we're not going to be doing yet. For now, the best solution is a case insensitive sort, IMO. The existing order has no obvious meaning, let's at least provide something that lets people find what they're looking for more easily.

[coke]

If anyone disagrees with my Jun 10th comment, please ping this ticket in the next week or so; otherwise we'll go with that for now.