On 12/28/20 11:49 PM, ToddAndMargo via perl6-users wrote:
I will accept your target audience:
"Someone who already knows how to program and
uses 'Raku.'"
I will also accept that the documentation is not for me
or anyone else trying to learn Raku.
We explained that there are two types of documentation, and that is the
target audience for *reference* documentation. The other type of
documentation is tutorial, which *is* for people trying to learn Raku.
This is different
than any other programming language I have used, but
it is what it is. Not my call.
And by your description of the target audience, I am
correct when I say the documentation is meant for
those that already know what they are doing.
"language expressed in concise formal notation, and
is not to be confused with tutorials"
Well now, they need to get on the same page as you:
https://docs.raku.org/language/classtut
"A tutorial about creating and using classes in Raku"
It is clearly stated that it is a tutorial, although
it is not. It is what you describe above. This is
part of my frustration.
That page is a tutorial, not reference documentation. It does not
attempt to provide a concise and complete description of one feature of
Raku in formal notation. It provides narrative and examples proceeding
from simple to complex forms in pursuit of a goal of explaining the use
of classes in Raku. That is a tutorial. Not all tutorials assume the
same starting point for the reader, and tutorials on more advanced
features of a language must assume the reader has familiarity with more
basic prerequisites. For instance, a tutorial on lookahead assertions in
Perl 5 regular expressions will assume that the reader knows what
character classes and quantifiers are and will not explain them again.
Therefore tutorials need to be consumed and understood in a certain
order by the newcomer. Designing and presenting that order so that the
reader does not get lost takes considerable skill. Generally, it
requires a veteran teacher working closely with an editorial team that
provides feedback from expert peers and novices alike in a lengthy
evaluation phase. The highest quality tutorials will include exercises.
Fortunately, all that work has already been done for Raku by just such a
teacher and team. You can find the result at
https://learning.oreilly.com/library/view/learning-perl-6/9781491977675/
This thread is titled after the cosine page, which is reference
documentation. You keep wanting reference documentation to be changed to
do the job of tutorial documentation. It would end up being bad at both.
That's not going to happen.
