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

Landing page for Documentation

Thread Next
From:
Richard Hainsworth
Date:
October 3, 2018 05:14
Subject:
Landing page for Documentation
Message ID:
7872183a-e904-4e10-ace6-bb8a01b0bf66@gmail.com
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

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About