On 28 Dec 2020, at 13:54, Richard Hainsworth <rnhainswo...@gmail.com>
wrote:
Todd,
Some of what you have said in this email list over the years has been very
valuable. You ask questions that get some very illuminating answers. I
wrote a Module just for you (although I' still trying to get it to work on
Windows) and it inspired me to look much more deeply at GTK::Simple, which
I have just become the maintainer for.
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).
However, the balances between prolixity and brevity, examples and
assumption of knowledge, exhibited in the Raku Documentation do by and
large reflect a community consensus.
It is polite in a community of rational human beings to accept what seems
to be the general consensus, even if you do not agree with it. By
continuing to demand your views about documentation should be accepted
without any support from anyone else, is quite irritating. So please try
to find a different way to express ways to improve the documentation that
will not piss people off.
You have suggested in this email list a variety of 'keepers', which seem
to be the way you document your use of Raku. However, these 'keeper' texts
are full of spelling mistakes, indicating you do not use a spell-checker,
and also are ambiguous or technically wrong. Personally, I have not found
your keepers to have been any use at all. But they may be useful to
someone. Even worse, it is not possible for me to find a collection of
your keepers because they are in posts to this email list, and I am not
going to search through thousands of emails for your keepers on something
whose keywords I would need to guess at. So the form you have made the
keepers available is not easily accessible.
In addition, the way the Raku community has evolved to work is to make
changes to Documentation, whether Tutorials or Reference, by actually
suggesting changes. If you look on the upper right of any primary document
(the docs.raku.org site displays pages that are both automatically
generated from primary documents, and the primary documents themselves -
basically the documents referenced from the home page), you will see a
Pencil icon. Click on that, and you will be taken to the github site and
you can directly edit the document. The change is then submitted as a Pull
Request, and it will be reviewed. If the change is seen to be reasonable,
it is included.
In this way, every single member of the Raku Community has the ability to
make or suggest a contribution.
However, a word of caution about human nature. If you go and try to
completely change all the documentation to the way you want it, trashing
everything that has already been contributed, it is extremely unlikely
that your amendments will ever be accepted. Further, you run the risk that
contributions with your name will never be considered by the Core
Developers because they have rejected PRs you made before.
Contribute in a way that enhances the Documentation, and your work will be
praised.
I hope whatever end of year, mid-winter or religious festival you
celebrated was festive, even in our pandemic afflicted world, and I wish
you a safe and productive CE 2021.
Regards,
Richard
On 28/12/2020 11:55, ToddAndMargo via perl6-users wrote:
On 12/25/20 8:10 AM, Ralph Mellor wrote:
On 12/23/20 4:28 PM, Ralph Mellor wrote:
If a method does not explicitly specify its invocant type, it is
set
to the type of the enclosing class.
But it does not specify an invocant. It just leaves it blank
This is how it works in Raku source code. If there's no signature at
all,
or if the invocant is blank, or if the invocant's type is not specified,
its
type is the type of the class which encloses or composes the method
(or `Mu` for a mainline `my` method).
<snip>
Hi Ralph,
What is used in the source code is written for a
purpose that is different from the documentation
in that the developers are expected to be freakin'
geniuses and know Raku like the back of the hand.
The source code is NOT meant to teach.
If you have seem some of my other letters lately, you
know I have been grubbing around in the source code.
It can be rather enlightening.
Now my technical opinion is that the documentation is
for a different purpose that the source code. It is
to teach those who are not freakin' geniuses. What
you seems to be telling me is that the two should
match.
So basically if I knew what I was doing, I would know
all the defaults, and I could just use the source
code and would not need the documentation.
The documentation need to show all the defaults.
The documentation's purpose should be to teach,
not to repeat the source code.
-T
