On Sat, Dec 7, 2019 at 12:04 PM ToddAndMargo via perl6-users < perl6-us...@perl.org> wrote:
> On 2019-12-07 03:00, Tom Browder wrote: > > Forgot to reply to all. > > > > ---------- Forwarded message --------- > > From: *Tom Browder* <tom.brow...@gmail.com <mailto:tom.brow...@gmail.com > >> > > Date: Sat, Dec 7, 2019 at 04:58 > > Subject: Raku, docs, help [was: Re: vulgar?] > > To: ToddAndMargo <toddandma...@zoho.com <mailto:toddandma...@zoho.com>> > > > > > > On Fri, Dec 6, 2019 at 23:23 ToddAndMargo via perl6-users > > <perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote: > > > > On 2019-12-06 18:34, Tom Browder wrote: > > > On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users > > > <perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote: > > >> > > >> On 2019-12-06 04:19, Tom Browder wrote: > > > > > > Todd, I was a bit harsh in my last reply, but I do see a huge difference > > between a bug report and a PR. In the PR, you have to show exactly what > > the wording should be in its entire context, while in the bug report > > your suggestions are less in context. To me, that automatically > > increases the friction in the conversation. > > > > Some other points about help via comms other than email that are > > valuable to me: > > > > 1. when using IRC, it is easy to put chunks of real code into a Github > > gist. That way everyone can see it and discuss it by line number or > > other reference > > > > 2. on the #raku channels, there is a built-in REPL so all can see your > > code chunks in action > > > > Finally, I really don't have any more good arguments about your > > discontent with the docs, but I leave you with these words about my > > experience here: > > > > Any help you can contribute to the docs will usually be greatly > > appreciated, but you are better off to start in small bits, correcting > > typos, improving grammar, etc. > > And I agree with you that much of the descriptions are in "IEEE-ese." To > > help with that I have added several "cookbook" examples in such areas, > > as much to help me as to help others. Given the way I've seen you > > operate I think that adding better examples from your "keepers" would be > > very useful. > > > Merry Christmas! > > > > -Tom > > > > P.S. One more thing about Perl vs. Raku docs: I believe over the years > > there has been much money applied to the Perl infrastructure by > > commercial users of Perl, especially in the early days of the Internet. > > On the other hand, I believe Raku has had comparatively little > > commercial support and has had to rely on those unpaid people who love > > the language and its community and who freely donate their time to its > > improvement. It can only get better, but maybe not with quite as steep a > > growth curve as Perl has had. > > Hi Tom, > > Seems I was a bit blunt with my criticism of the docs and > hurt a lot of feelings. > > Perl 5's docs are a good example of Kaisen (constant change) > as is the Linux kernel and Fedora. Raku itself is also > a masterpiece of Kaisen too. The docs are not though, but > maybe they will catch up in the future. Probably the > developers are too busy doing their magic (that was > a compliment -- not one get their nickers in a twist). > > What would be nice is if there was place to put suggestions > as to improvements to the docs. > > Guys like me a perfect for such as we do not know what > it is suppose to say and don't see what we expect to see. > > An example of IEEE-eese would be > https://docs.raku.org/routine/contains > > method contains(Cool:D: |c) > > And > > Coerces the invocant Str, and calls Str.contains > on it. Please refer to that version of the method > for arguments and general syntax. > > Must win the IEEE-eese award for the week. I have no > idea what was just said. What the dickens is `|c` > anyway? > This is not IEEE-ese. Earlier, you defined IEEE-ese as Technical written material that uses so many obscure terms and unnecessary technical jargon mixed with deliberate obscurities that even a reader with intimate knowledge of the subject are confused. Example: read any published paper from IEEE. That is, IEEE-ese uses technical jargon *unnecessarily*. By contrast, what you quoted is simply using technical jargon *clearly and precisely*. (It does have a typo, the word "to" is missing between "invocant" and "Str"; and "Str.contains" links to the wrong anchor in the page.) It can probably be hard to tell the difference, if you aren't familiar with the technical jargon in question. But in this case, if you know what an "invocant" is, and what it means to "coerce" something, and to "call" a method, then the meaning is clear; and in fact, the way it was written seems like the obvious way to write it. If you don't know what those words mean, then the meaning won't be clear. (But even then, clicking the link on "Str.contains" and glancing down that page a little should give you some hints.) Perhaps, to make it easier for you to understand, the docs could stop using words like "invocant" and "coerce". But that makes it *harder* for people who do understand these words, because those people then have to read more words and translate them into their precise understanding. Perhaps it can be rewritten to make it clearer for people who don't know the jargon while not losing concision or expressiveness for people who do. But that's not necessarily an easy thing to do; and someone who doesn't know the jargon is unlikely to do it well. As for `|c`, that's part of the type signature. For people who can read type signatures, glancing at the type signature of a method can be much easier than reading a possible-imprecise description of how to use it. If you can't read type signatures, you're out of luck; but that's no reason to hide them from people who can. If you type `|` into the search box, there's an entry under "Reference" named "| (parameter)" (which admittedly also links to the wrong anchor in the page), and another under "Syntax" simply named "|", and either one of those will (with perhaps a bit more reading and following links) take you to https://docs.raku.org/type/Signature#Capture_parameters which describes what it does. > And I know how to use contains! I use it a ton. If > I had relied on the doc, I'd be in the dark. > > I have only used the #raku channel a few time. I used > the #perl6 one a lot. Seems the the #raku channel > has some powerful new toys! The channels are wonderful > if you can catch someone of newbie duty. > > I have been using the REPL utility a tons since I found > out about it yesterday. What a marvelous tool! I hate > to ask how long it has been around and I did not know > about it. It even takes subs! > > -T > > Did you catch my WinPopUps post? >
