On 2020-08-25 20:28, dan...@codesections.com wrote:
I noted it over on the survey, but the things I would
like to see upcoming are
1) documentation that is written for both the beginner
and the advanced user. Currently, it is only written
for the advanced user, who does not need it. The
documentation should eventual be on par with Perl 5's
Perl Docs where everyone can use it.
It's interesting to hear your perspective on this, which is very different from
my own. I've only spent a couple of months with Raku, but my impression of the
docs is that they are *extremely* accessible to beginners like me. I've almost
never run into a basic issue that the docs didn't address in depth, and the
questions that have stumped me have typically been more advanced/esoteric areas
where the docs didn't go deep *enough*, not beginner areas at all.
I wonder why our perception of the docs is so different. I've been trying to
contribute to the docs more in the past few weeks, so maybe I can play a small
part in making that situation better for us all.
Best,
Daniel
Hi Daniel,
When I program, I always have the Docs up in a window
for easy access. It is a habit.
My perspective on Raku's docs are that they are meant
as a refresher for those that already know what they
are doing.
"If you don't understand the Docs, it is because
you don't know what you are doing."
"If I knew what I was doing, why would I need the
docs?"
Let me expound:
Lets go to operator classification:
https://docs.raku.org/languag/operators#Operator_classification
"Operators are just subroutines with funny names. The
funny names are composed of the category name (infix,
prefix, postfix, circumfix, postcircumfix), followed
by a colon, and a list of the operator name or names
(two components in the case of circumfix and
postcircumfix). A expanded explanation of all these
operators and what they mean is included in this table:
https://docs.raku.org/language/operators#Operator_classification";
Okay, "funny names" means they are "esoteric"
https://www.wordnik.com/words/esoteric
adjective: Intended for or understood by only a small
group, especially one with specialized knowledge
So basically "What that suppose to mean?". And the table
is even worse esoteric. So "insider knowledge" is required.
This is just poor technical writing.
Now lets go to my attempt to solve the issue in Operator
Classification:
RFE: add some links to Operators #3175
https://github.com/Raku/doc/issues/3175
You will note, I fully described what these esoteric
terms are. It is a great explanation too. You may want
to copy and paste it.
The response from JJ (Hi JJ) was:
"I don't really think we should go down to that
level of detail."
If you don't want the terms to remain "insider knowledge",
yes you should.
JJ also referenced the table that made things worse.
and the Docs remained as "Intended for or understood by
only a small group, especially one with specialized
knowledge".
And we are full circle back to
"I don't really think we should go down to that
level of detail."
"If I knew what I was doing, why would I need the
docs?"
You will understand if I point out that that was the
LAST time I tried my hand at improving the docs:
"grand me the wisdom to know the things I can and can
not change".
Now when you are writing docs, you need to start small
and work up to the complicated. Raku's docs are
"in your face" and do not explain slowly and work
up. And they rely on specialized knowledge.
For instance:
A booboo and an rfe in contains documentation #2334
https://github.com/Raku/doc/issues/2334
Note that I got my way on this one and the changes I
wanted were introduced. I was given somewhat of
a bad time about the use of the word "haystack". I
pushed for it because I though it put the word
"needle" in context:
"Given a Str invocant (known as the haystack) and a
first argument (known as the $needle), it searches
for the $needle in the haystack from the beginning
of the string and returns True if $needle is found.
If the optional parameter $pos is provided, then
contains will search the haystack starting from $pos
characters into the string."
And I like it. Very few of the others are this way.
This one also started with an error in the cryptogram
as well. (That is another complaint about the
documentation. The cryptograms are often wrong.)
And there should be zero tolerance for "insider knowledge".
And "in your face example" would be one of my all time
favorite routines which is "lines". I use "lines"
ALL-THE-TIME.
https://docs.raku.org/routine/lines
"Defined as:
sub lines(Str(Cool))
method lines()
Coerces the invocant (and in sub form, the argument)
to Str, decomposes it into lines (with the newline
characters stripped), and returns the list of lines."
Okay, that sorta-kinda says what it means.
Do you see this explained?
To pick out particular lines:
$ cat Lines.txt | raku -e '.say for lines()[3,2,5]'
Line 3
Line 2
Line 5
If it is, it is buried somewhere.
And what goes inside the ()? That may seem like a dumb
remark (especially since I live and die in Top Down and
know very well what the () does) but it is a common mistake
I make with lines is forgetting the () when using the [].
The documentation need to be accessible to EVERYONE, beginner and
advanced user. Also keep in mind that the developers
have their own set of documentation to go by.
So, basically the documentation is what it is. My way of
coping is to create my own set of documentation, which
I call "keepers". So far I am up to 220 of them. You will
see me occasionally posting some of them to this group.
If you are having trouble with a particular subject
and I have a keeper on it, ping me and I will send it
to you.
Hope that explains it. I ADORE Raku. The only thing
I dislike is the documentation.
Sorry for being so long winded.
-T
