I have just started a review of the documentation for perl6.
When I hit `https://docs.perl6.org/language.html` I get a list of sections that is the same as the alphabetical list of pod files in `github.com/perl6/doc/tree/master/doc/Language` without 00-POD6-CONTROL.
One of my biggest issues about the Language page is its unstructured listing.
I looked at 00-POD6-CONTROL and found that the categories were much more useful than a straight enumeration of files.
Then I looked at the makefile in the repository, which appears to generate documentation based on 00-POD6-CONTROL.
I clicked around on the perl6.org site to see whether I could find a landing page for the documentation that is structured as in 00-POD6-CONTROL, but couldn't.
So, the question is: why is 00-POD6-CONTROL not used for the Language web page? That is why does docs.perl6.org/language.html not reflect the structure in 00-POD6-CONTROL?
I do - vaguely - remember a discussion about documentation categories. Was it resolved in favour of a straight enumeration of files?
If so, would someone please explain why the most visible public-facing description of perl6 is better as an unstructured clutter, rather than a structured list with some clue about how each file fits into a whole?
If the problem is that different people have different ideas about structure, then why not make it possible to have multiple structures, switchable with a button in html. It seems from 00-POD6-CONTROL that the ordering can be easily changed. This would indicate that multiple CONTROL files could be created using the same programs to generate them.
I actually disagree a bit with the ordering in 00-POD6-CONTROL, in that I would put the 'General Reference' section first. But any order is better than no order.
Regards, Richard aka finanalyst
