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.
