Nobody said not to do it. Please make more documentation available to the public.
But that doesn't mean that these docs need to change. It's reference, not guides. And also it doesn't need to be a wiki. You could do everything on GitHub, where most people already do their collaboration, with the plus that you can deploy your repo as a static site for free. In fact, you could also contribute guides to the official docs, just collaborate over GitHub. You can do reviews line by line, and anyone who works in the docs would get automatically updated. I would like to discuss your idea anyways, so you could drop me a line on irc. I go by veesh on freenode and irc.perl.org Have a wonderful day, Veesh On Tue, Dec 10, 2019, 13:04 ToddAndMargo via perl6-users < perl6-us...@perl.org> wrote: > On 2019-12-10 02:37, ToddAndMargo via perl6-users wrote: > > On 2019-12-10 01:14, Simon Proctor wrote: > >> > >> > >> On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users > >> <perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote: > >> > >> On 2019-12-09 07:21, Simon Proctor wrote: > >> > I think this does highlight something we probably should document > >> more. > >> > > >> > How to read signatures. Because it's a *very* powerful part of > the > >> > language that if you don't understand you're only using it at > >> half strength. > >> > > >> > multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> > >> Bool:D) > >> > > >> > If not some documentation magic, it's a core part of the > >> language. It > >> > tell you this method is called on a defined Str (Str:D:) it > >> takes 2 > >> > positional arguments which have to be defined Cool types ($needle > >> and > >> > $pos) and it returns a Boolean. > >> > > >> > That is the code as it will be written in the Str Role. > >> > > >> > I *highly* advise learning how signatures work. > >> > >> > >> > >> Firstly can I say I admire the fact that you are using Raku in > >> production on a regular basis. > >> > >> Hi Simon, > >> > >> Did you see the How To post I made on ".contains"? At > >> the bottom of the How To, I take apart the signature > >> and explain each part. > >> > >> > >> I did. It's pretty good except your understanding of the first part > >> Str:D : > >> > >> This indicates that this method will be used when it's called on a > >> defined (D) String instance. The wording you use is a bit weird and it > >> speak to my beliefe that you don't really get Signatures. > >> > >> Do you see anywhere in the docs where how to read > >> signatures is explained? (Don't get any ideas. The > >> signatures should not be there to start with.) > >> > >> > >> Apart from here? https://docs.raku.org/type/Signature > >> > >> I read through this (and some bits on Captures) and was able to get > >> enough information to give a talk at the Perl Conference in Glasgow in > >> 2018. > >> > >> Here's the video : > >> > https://www.youtube.com/watch?v=V5rWtKIVmJc&list=PLQTGmZanuBovAKtE0dDs7rdTUvxnOwvEz > >> > >> > >> Larry was there, it was rather stressful. > >> > >> An aside on the signatures: what is and what is > >> not a separator can blow your mind. > >> > >> > >> Not really. comma seperates arguments, colon can be used if you want > >> to specify information about the calling instance or class. > >> > >> > >> Do you think it help me or anyone else understand > >> how to use ".contains" because I explained the > >> "Signature"? Seriously? > >> > >> > >> No, I don't think you NEED the signature to understand contains. I > >> think that understanding and being able to read signatures CAN help > >> you understand more about how a subroutine or method works. > >> > >> To answer the question, look at all the various > >> teaching manuals out there for Raku. Do you see a > >> SINGLE ONE, other that the one I posted, that > >> uses the signatures as a teaching tool? > >> > >> > >> I have every single book written about Raku (though of course most are > >> Perl6) and most of them explain Signatures. > >> > >> Again I'm not saying that they should be used as a teaching tool, but > >> the documentation has a lot of uses and it's not just teaching. > >> > >> > >> And notice that I put the signature explanation > >> at the bottom AFTER I explained how to use the > >> function (method). This is akin to the good math > >> teachers that run circles around bad math teachers > >> in both mechanics and theory by FIRST teaching the > >> mechanics and them teaching the theory. When > >> teaching, you should never start with the theory. > >> The docs do just that. > >> > >> > >> So when I was first reading the docs I mostly just skipped over the > >> signatures to get to the rest of the code. I didn't try and understand > >> them too much "Oh this takes a string, makes sense". > >> > >> Over time I did start to learn them and that helped me getting better > >> at programming Perl6. > >> > >> > >> The "Signatures" in the docs only confuse and often > >> have mistakes in them. Trying to get them corrected > >> is a fools errand too. > >> > >> > >> How do you mean? If there's a mistake in the signature you can fix it > >> in the docs and put in a pull request to get it updated. > >> > >> The signatures are how the developers talk to each other. > >> And judging by the results of their work, it works > >> marvelously for them. This kind of information is > >> not appropriate for standard Rakoon that just wants to > >> write code. > >> > >> > >> Here is where I have to respectfully disagree with you. > >> > >> Writing Raku code without using Signatures and Multi Methods is like > >> owning a Jaguar and only driving in first gear. I mean *technically* > >> you can get where you want to go but you are forgoing a lot of the > >> power of the language. > >> > >> I generally write a couple of Raku scripts a week (more if I've got > >> the time) and they *all* use Signatures. Most use multi methods too. > >> > >> You don't need to know how much current affects an LED > >> diode to read the time on your digital clock. This > >> is what the signatures are doing. > >> > >> The Signatures only confuse. They need to be left to > >> the developers. > >> > >> > >> This is the problem, until you stop treating signatures as some kind > >> of weird messaging system only to be used by "the developers" you will > >> be coding with one hand tied behind you back. You'll also keep asking > >> the same questions over and over again. > >> > >> Please take a moment to really try and understand them. It will blow > >> your mind. > >> > >> -T > >> > >> > >> With respect. > >> > >> -- > >> Simon Proctor > >> Cognoscite aliquid novum cotidie > >> > >> http://www.khanate.co.uk/ > > > > Hi Simon, > > > > Thank you for such a wonderful, respectful letter. You make > > a lot of sound points. > > > > "Str" > > means it want to be fed data as a string. Str.foo > > > > was meant to bring the complicated down to a simple, understandable > > level. Is not your "This indicates that this method will be used when > > it's called on a defined (D) String instance" doing the same thing only > > far more words and > > far more technical? > > > > Layman's terms, the data from Str (the Haystack) gets > > input (fed) to .constains which looks to see if the fragment > > you gave contains (the Needle) is inside the Haystack. > > If it does, it return a Boolean True, otherwise it return False. > > > > I too usually skip over the signatures and look at the > > examples. Typically I will run an example, if it fits > > what I am after and play with it. I have caught the examples > > crashing at times too. > > > > Maybe I would look at the signatures more, *if* I trusted > > them to be accurate. I don't. Yes, I should report them > > when I find them wrong, but it requires a lot of arguing > > to get them accepted and I just don't have the time. > > The culture on the bug reporter is more akin to > > LibreOffice's culture and not Fedora's. > > > > As far a separators, both commas and colons are used as separators. > > Colons are used for other things too. It > > is not always apparent what a colon is being used for. > > > > My main gripe with the documentation is how it is presented. > > One does not need to know how to do Matrix Math to > > add two numbers. That is jumping too far ahead. The > > docs should not expect the user to have advanced level > > knowledge of Raku. > > > > Just an aside, my all time worst programming language is > > Windows Batch programming. It must have been designed by > > the devil himself. But you know what, even the devil put > > help /? > > to give a simple list of its functions. This goes back > > to jumping too far ahead and expecting the user to have > > advanced knowledge of the subject. > > > > If I might posit a solution that would make both of us > > happy, lets look at how Math is taught. Those teacher > > in my college that first taught the mechanics and then > > the theory absoulty wiped the floor with those teachers > > that first taught the theory and then expect the > > student to pick up the mechanics by osmosis. > > > > So, follow that principle, > > > > First teach what the function does and then after stating > > what it does and how to use it (the mechanics), then > > AFTER that give the theory (the signature). > > > > Using this method, I bet folks start picking up how to use > > the signature 1000 times faster. I know I would. As it stands, now the > > signature is more of a migraine to me > > than a help. > > > > My four favorite "methods" that I use all the time > > are "contains", "kv", "words", and "lines". I ADORE > > Raku. > > > > My next big Raku project is to convert my Cobian Backup > > wrappers from Batch to Raku. I have started with > > supporting modules. So far I have my WinPops and my > > WinMount completed. > > > > I love modules (I did a YUGE amount of Modula2 in my past) > > I really enjoyed your letter, Thank you! > > > > -T > > You know, maybe my idea on a Wikipedia style project > for the documentation would still be good. I would > certainly beet the heck out of posting and arguing. > And it would get a lot more folks involved. >
