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.
Many thanks,
-T
