On 29/12/2020 18:49, ToddAndMargo via perl6-users wrote:
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"
I assume what you need is a set of tutorials for beginners try
https://www.google.com/search?channel=fs&client=ubuntu&q=raku+programming++for+beginners
and hope for the best I guess. sorry I cannot help more just now
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
--
.~. In my life God comes first....
/V\ but Linux is pretty high after that :-D
/( )\ Francis (Grizzly) Smit
^^-^^ http://www.smit.id.au/
