On 12/28/20 11:29 PM, Peter Scott wrote:
On 12/28/20 10:57 PM, ToddAndMargo via perl6-users wrote:
On 12/28/20 4:54 AM, Richard Hainsworth wrote:
So please take what I say now as a plea for you to adapt a little,
not to get pissed off with us even though you do seem to have pissed
some of us off.
You have very definite ideas about what the documentation should and
shouldn't be. You have stated them over and over again. The Raku
community at large - based on replies from multiple individuals over
the years - disagrees with you.
The Raku community has come to the concensus that there is a
distinction between Tutorials and Reference, and that the
Documentation site should contain both. Tutorials define how to use
some aspect of Raku, with example text and explanation. Reference
tries to cover as much of the language as possible, covering all the
methods/subs/names/types etc as possible. Reference is written for a
person who already knows how to program and who uses Raku. The
assumption is that if a person reading a reference does not
understand some term, then s/he will search in the
documentation on that term to understand it.
No set of documentation standards will please everyone - that's life.
Even so, there ARE STILL areas of the Raku documentation that are
lacking (just look at the issues on the Documentation repository, any
of them raised by our indefatigable JJ).
Hi Richard,
When deciding to write a technical article, the
VERY FIRST thing you have to do is determine
your TARGET AUDIENCE.
In a single sentence, please state for me what
you believe the TARGET AUDIENCE is for the
documentation.
Richard stated the target audience for reference documentation quite
clearly: Someone who already knows how to program and uses Raku.
Multiple people have told you many times over several years that the
purpose of reference documentation is to provide a complete description
of the elements of a language expressed in concise formal notation, and
is not to be confused with tutorials. Your condescending tone indicates
you haven't listened and are still trying to convince them that they are
wrong. It isn't going to work.
Peter,
I am, not being condescending. If you sense anything,
it is frustration.
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. 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.
Please do not confuse frustration with condescension.
-T
