doc
doc copied to clipboard
Raku
Sort Table of Contents
As reported in https://github.com/perl6/user-experience/issues/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.
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.
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.
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 [email protected]:
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 https://github.com/perl6/doc/issues/392#issuecomment-182848899.
Sylvain "Skarsnik" Colinet
Victory was near but the power of the ring couldn't be undone
@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?
On Thursday, February 11, 2016, Skarsnik [email protected] 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
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.
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.
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.
I'm pinging this ticket now. What happened to it? Do we have a proper order? If that's the case and there are problems somewhere else like having categories, I suggest to open a separate discussion for that.
I'm not so sure about this. Right now they are in the same order as in the original document, which I guess has some merit to it, because it's how it was intended by its author(s). You can still search within the page using Ctrl-F and the website search. As @AlexDaniel has commented, we would need a major refactoring of htmlify.p6 to add JS code that sorts this. I don't see how that effort would have a good return on investment by offering an arrangement of contents that would be arguably better. There's a point in the rearrangement of documentation, however... But once again, it escapes the boundaries of this particular issue.
One thing that could be done is similar to the mod I made to htmlify.p6 at 3f9f9aac4e569fd5524c868b32b77e3040846257
Since tables are now sortable, maybe we could throw this inside a table and just make it sortable by default?