❤️
> 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
