On 12/29/20 7:05 AM, Peter Scott wrote:
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.
Hi Peter,
Interesting read. The tutorial I questioned was a tutorial
for advanced users, not those learning Raku. If it was
for those learning Raku, it would have defined the terms.
In other words, the tutorial for those that do not need
the tutorial.
When I first saw the tutorial, I was very happy. It was
going to tutor me on classes, objects and methods. When
I started to read it, I could not believe how poorly it
was done. It totally baffled me. It said "tutorial".
I know what they are now though. I ask a fried on another
programming forum who has an extreme gift for teaching.
He taught me in *O-N-E S-I-N-G-L-E P-A-R-A-G-R-A-P-H*.
OOP (object, orientated programming) is "elegant" and
I can think of a ton of uses for it. I may never use
an associative array (hash) again. And I ADORE hashes.
Now when I look at that tutorial, I understand it
(well most of it), BECAUSE I ALREADY KNEW WHAT OOP
IS IN RAKU. So, I no longer need it.
I do like your idea about using a teacher to put
these things together. But you must be careful of
teachers as you must with all professions. Teaching
is a gift. I would posit that most teachers
do not have it (arrogant, condescending blowhards
with elbow patches and beards to make them look older).
The ones that do have the gift, open a whole new world
up for you. They are truly a gift to the world.
And it is pretty easy to tell them apart. If you
ever heard the phrase cross their lips "the
solution is intuitively obvious and left up to
the student to figure out for themselves" then
you just found the bad ones. The bad ones
also do not care if you do not understand them: you
are just stupid.
Now for cos. The "reference" for advanced users
"presumes" a lot in the definition line:
method cos()
1) it presumes you know what class it is in (Cool)
2) it presumes you know what the output structure will
be (Num)
How does this help ANY user, advanced or not? Well
"the solution is intuitively obvious and left up
to the student to figure out for themselves".
The text later does fill things in a bit.
Would it have killed ANYONE to have written it?
method cos( Cool:d: --> Num )
Why do we even use these definition lines if
we are not going to take advantage of their
power? (And make sure they are correct.)
And it uses the board term "Coerces the invocant",
which you can only figure out through context
(used in this way, "invocant" is the supplied
value to method, but that only by context.)
And in fairness, since this was written for an
advanced user, an advanced user would catch that
immediately.
And back to OOP. Any one who tried to over complicate
OOP is trying to baffle you for what ever reason
I can only speculate on. OOP is elegant and RAKU
shines with it. And it is REALLY EASY.
And just an aside, those that really know what they
are doing, love to share. They are like cans of
compressed air that no one will push the valve on.
When they do finally get an audience, it is difficult
to get them to shut up. Someone is finally listening
to them. This is a way to tell posers apart from
the real deal. Posers withhold information.
-T
"It ain't what you don't know that gets you
into trouble. It's what you know for sure
that just ain't so."
--Mark Twain
