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
