Hi El mié., 3 oct. 2018 a las 7:14, Richard Hainsworth (<rnhainswo...@gmail.com>) escribió:
> I have just started a review of the documentation for perl6. > > When I hit `https://docs.perl6.org/language.html` > <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` > <http://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? > Simply because there has been no time to do it yet. The tooling part of the Perl 6 docs is complicated and needs an overhaul, and there were already some pains to implement that particular part; that second part will have to wait. > > > I do - vaguely - remember a discussion about documentation categories. > Was it resolved in favour of a straight enumeration of files? > No, it wasn't, but in the same way that so many things in the documentation repo (and, for that matter, others) lays in waiting someone has the time to do it. > > 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? > No, it's not. But someone's got to do it. > > > 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. > I tend to agree with that. Cheers JJ
