On 12/29/20 3:51 AM, Richard Hainsworth wrote:
What it is would be what you stated previously:
"Reference is written for a person who already
knows how to program and who uses Raku"
This is taken out of context. I said the Raku community has come to a
consensus that DOCUMENTATION should contain both *tutorial* and
*reference*.
You specifically stated:
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.
But Raku documentation could not be 'standard technical writing', if
such a thing exists.
They teach it in our universities. They call it
"technical writing"
Raku documentation should be compared to
documentation about another newish language, such as Rust or Go, or
Haskell. I think it compares well.
A better comparison would be from where we came. A
language also created by Larry Wall that transitioned
into Perl6/Raku: Perl 5 and Perl Docs. Raku does
not compare so well at all. Perl Docs is not written
only for advanced users.
Actually if I want an answer to a programming question, I would turn to
StackOverflow, and Raku there does not give any ceramic references.
I find them extremely helpful at times too.
