On 2020-08-28 07:49, Brad Gilbert wrote:
Now with all of that said, it is little wonder why Todd has difficulties
with the function descriptions where others don't.
I also think that if we just replaced what we have for something that
works for Todd it might make it more difficult for others.
Again because his brain is more unique than most.
Hi Brad,
I am weird, not autistic. But I do see things that
other people can not see, which is why I am so good
at troubleshooting.
By the way, I adore the way Larry Wall writes. He
is extremely good at explaining things. I think
he is damned brilliant.
Also, I can easily tell well written documentation from
poorly written documentation. Perl 5's Perl Docs
is a great example of well written documentation.
And I am not after a total trash and replacement. The
framework used currently is good. It is just not organized
such that it is usable by beginners.
A good point would be to start with the cryptogram, and then
decompose it
this does this
this does this
this does this.
Now looking at
https://docs.raku.org/routine/lines
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.
Good so far, but were is $limit and :$chomp stated?
Somewhere in the bowels of the page? Why is it
missing from the cryptogram?
It should state right away what the parameters are
and what they do.
You have Linux installed on your machine. Try this
$ nmcli -- help
In your face, tells you what you need. Defines each
term.
And, not to kick a dead horse, when you use esoteric
terms, meaning those requiring specialized knowledge,
you need to link or define them. But you don't.
A great example of this shortfall can be found over on
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.
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.
So to summarize, the framework is there and mostly
good. It just need to be refined with the beginner
in mind. Start small and work up. And remove the jumble.
Here is an example of a wonderful clean up:
https://docs.raku.org/type/Str#method_contains
When writing documentation, remember "if the reader knew
what he was doing, he would not need the documentation".
And "the solution is intuitively obvious and left up
to the student to figure out on his own" is useless
rubbish.
Also, please keep in mind, that I have tried my hand at
upgrading the documentation, I just cant get past JJ.
"Grant me the wisdom to know the things I can change
and can not change and to know the difference."
-T
