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-users@perl.org <mailto:perl6-users@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-users@perl.org <mailto:perl6-users@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?
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?
