El sáb., 7 dic. 2019 a las 17:24, Philip Hazelden (< philip.hazel...@gmail.com>) escribió:
> 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 > Created issue 3112 https://github.com/Raku/doc/issues/3112, fixed and redeployed. Thanks for the report. https://docs.raku.org/routine/contains Cheers JJ
