develooper Front page | perl.perl6.users | Postings from October 2018

Landing page for Documentation

Thread Next
Richard Hainsworth
October 3, 2018 05:14
Landing page for Documentation
Message ID:
I have just started a review of the documentation for perl6.

When I hit `` I get a list of 
sections that is the same as the alphabetical list of pod files in 
`` without 00-POD6-CONTROL.

One of my biggest issues about the Language page is its unstructured 

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 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 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.



aka finanalyst

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About