The best way I can be explicit about what the Perl 6 docs are missing is holding up the official Python docs for any version [0] as a standard, and saying that Perl 6 needs that; and, for onboarding, especially a Perl 6 equivalent of what Python has as its Tutorial (the Language Reference and Library Reference are also important, though the latter might need rethought more fundamentally for Perl 6, with its more-complete independent modularization as opposed to batteries-included standard library.)
Personally I really dislike the Python documentation for an average module. Return types seem to never be specified and everything is written too much in a tutorial fashion.
However, you bring up a good point as to the Language Reference / Library Reference. I'm not sure if there's anything remotely comparable for Perl6. I'll get looking into what it would need to add it. Also fwiw Perl6's stdlib is not as bare as 5s.
What style would you want it in if not tutorial? You're in the reference to learn something (possibly again), right? That's a situation tutorial style is well suited for.
Well, when many programmers look up something in a reference, they are looking for details about the API (functions/modules/variables/etc), not necessarily a tutorial on how to use those things. Examples can be good, but usually you are not expecting a full-fledged tutorial. Reference manuals are usually full of nuts-and-bolts details. Examples I can think of are O'Reilly books that have titles that end with "Reference" verses ones that start with "Learning".
Any effective tutorial is going to gloss over some, potentially lots, of infrequently used confusing edge cases. That's great sometimes. But when I'm trying to understand the infrequent and confusing edge case, a generic tutorial is the last thing I want. Git's man pages get dumped on a lot, but they're some of the best comprehensive reference documentation I can think of off the top of my head and are definitely not in a tutorial style.
Basically, I guess, I would like something like the Camel book for Perl 6.
There was one published by O'Reilly about ten years ago, but of course back then you could not say "apt-get install perl6" or something equivalent. Also, the language definition was far from finished, back then, so that book is probably totally outdated by now.
The Perl community, as far as I can tell, has no lack of talented writers, so I am optimistic something will be written before too long.
And really, I would like something I can read offline, preferably as a PDF. I know we live an always-online age, but really, I want something I can read on the train where I have no Internet access, and I want to be able to search the documentation without having to send a request to a web server.
I am aware there are of http://www.perl6.org/documentation/, but the docs there seem to be ... not organized in the way my brain is used to.
Another reference that just comes to my mind is the Python documentation, which IMHO is superb. It's well organized, concise and to the point, without being spartan.
Just to be clear, I do not expect you to do all that work, but if you want starting points what I would like Perl 6 documentation to look like, now you know. ;-)
> Just to be clear, I do not expect you to do all that work, but if you want starting points what I would like Perl 6 documentation to look like, now you know. ;-)
It is a little spartan at the moment, and it appears to be incomplete (which should not be surprising at this point). But it seems to be well-structured.
I have never written non-trivial amounts of documentation, so I can only guess, but I have the gut-feeling that structuring documentation well is pretty hard, much like interface design (both for APIs and UIs) is (to me, at least) very hard. So having a well-structured but incomplete Wikibook as a starting point is probably a lot better than vice versa. ;-) The parts that are there are well-written.
Can you be more explicit? I'm not a Perl 6 dev but I would love to help adoption and I'm not so bad at documentation.