On 2019-12-09 07:24, Curt Tilmes wrote:
The reference documentation (especially deep inside) is NOT intended for
brand new people to the language.
They need to start with the introduction, the tutorials, the books, even
classes (many are available for free on youtube).
That, and asking a lot of question, is what you have to do.
The reference documentation is for someone already somewhat familiar
with the language, but can't remember the exact calling sequence, or
order of arguments, or exactly what gets returned, etc.
Hi Curt,
So it is intended as a refresher for those that already
know what they are doing? Why do you even post them for
the general public?
Have you seem Perl 5's perldoc? They are extremely well done.
We need to follow their example. See any signatures in them?
Perldocs is written for the user, not the developer. Raku's docs, as
you just verified, are not meant for the general user
seeking to learn how to user something. This needs to change.
The MOST
important piece of documentation needed is the precise signature that
concisely presents that information. That is much more important the
accompanying verbiage.
If one hasn't yet learned what "()" ":D" or "-->" mean, I would kindly
suggest that they should review the introductory documentation or some
tutorials prior to delving into the detailed technical reference
documentation.
Did you see my post on .contians? At the bottom, AFTER I
explained the method, I took the signature apart. I do
understand the signature most of the time. A lot
of the time you can't tell if there is an error in the
or you just can't figure them out. Most of the time, I
just go elsewhere.
I have to rely on the examples.
Leave the signature to the developers where they belong.
Thank you for your forbearance.
-T
--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Computers are like air conditioners.
They malfunction when you open windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
