A grand idea on the documentation

Hi All,

I have a "grand idea" on how to fix up the documentation
I would like to pitch to the community:

Raku's documentation is pretty much unusable for
newbies and regular users do to its culture:
IEEE-eese like "method contains(Cool:D: |c)"
and so on and so forth.  Sometimes a usable
example sneaks through.  It is targeted at
the wrong audience.

It has been pointed out that the reason why Perl 5's
perldocs is so much better done that Raku's is that
Perl 5 has some industry funding behind it and
Raku is a volunteer effort.

To cope with such, I write my own keepers on
various parts of Raku.  I have posted a couple
of them here.  I am up to 190 of them now.

So here is my idea.  Since this is a volunteer effort,
lets not loose the value of my own 190 notes and
everyone else's contributions as well.

Lets create our own community documentation Wikipedia.

Make it so any Raku user can wax eloquent on any
part of the documentation.  Have it peer reviewed for
accuracy and content, and then published for all
to use.

This would shut me up complaining about the IEEE-eese
and give me and other a chance to contribute on
a major scale.  A true community effort.

And, chuckle, keep the guard dog constructively
employed, instead of coming up his a bazillions
way to say (put to music) "no, No, NO, no no no,
NOT A BUG, NOT OUR PROBLEM, no no no, I don't
think this applies".

Given time, we could have some awesome documentation!
And it would be all in one place, not spread out all
over the Internet.  It would be something we could all
take pride in.

And those versed in the IEEE-eese can still use
the original documentation.

-T
0
perl6
12/9/2019 2:05:26 AM
perl.perl6.users 1389 articles. 0 followers. Follow

24 Replies
72 Views

Similar Articles

[PageSpeed] 3

On 2019-12-08 18:05, ToddAndMargo via perl6-users wrote:
> Hi All,
> 
> I have a "grand idea" on how to fix up the documentation
> I would like to pitch to the community:

 > Lets create our own community documentation Wikipedia.


I would like "Community Documentation" placed
right next to "Documentation" on the Raku web
site.  When you arrive at the Community Documentation,
I would like to see

1)  An explanation of what it is

2)  How to sign up to contribute

3)  A list of requested command

4)  A list of completed commands

-T
0
perl6
12/9/2019 6:42:03 AM
--000000000000c936fb0599413f31
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

The Raku community has got a community documentation. It's called the
official documentation, and it's done by the community. You want to write
your own and help yourself and maybe others, there're lots lof places you
can do that: dev.to, Medium, your own blog. Even the "official" Raku Advent
Calendar or your very own.


El lun., 9 dic. 2019 a las 3:16, ToddAndMargo via perl6-users (<
perl6-users@perl.org>) escribi=C3=B3:

> Hi All,
>
> I have a "grand idea" on how to fix up the documentation
> I would like to pitch to the community:
>
> Raku's documentation is pretty much unusable for
> newbies and regular users do to its culture:
> IEEE-eese like "method contains(Cool:D: |c)"
> and so on and so forth.  Sometimes a usable
> example sneaks through.  It is targeted at
> the wrong audience.
>
> It has been pointed out that the reason why Perl 5's
> perldocs is so much better done that Raku's is that
> Perl 5 has some industry funding behind it and
> Raku is a volunteer effort.
>
> To cope with such, I write my own keepers on
> various parts of Raku.  I have posted a couple
> of them here.  I am up to 190 of them now.
>
> So here is my idea.  Since this is a volunteer effort,
> lets not loose the value of my own 190 notes and
> everyone else's contributions as well.
>
> Lets create our own community documentation Wikipedia.
>
> Make it so any Raku user can wax eloquent on any
> part of the documentation.  Have it peer reviewed for
> accuracy and content, and then published for all
> to use.
>
> This would shut me up complaining about the IEEE-eese
> and give me and other a chance to contribute on
> a major scale.  A true community effort.
>
> And, chuckle, keep the guard dog constructively
> employed, instead of coming up his a bazillions
> way to say (put to music) "no, No, NO, no no no,
> NOT A BUG, NOT OUR PROBLEM, no no no, I don't
> think this applies".
>
> Given time, we could have some awesome documentation!
> And it would be all in one place, not spread out all
> over the Internet.  It would be something we could all
> take pride in.
>
> And those versed in the IEEE-eese can still use
> the original documentation.
>
> -T
>


--=20
JJ

--000000000000c936fb0599413f31
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>The Raku community has got a community documentation.=
 It&#39;s called the official documentation, and it&#39;s done by the commu=
nity. You want to write your own and help yourself and maybe others, there&=
#39;re lots lof places you can do that: <a href=3D"http://dev.to">dev.to</a=
>, Medium, your own blog. Even the &quot;official&quot; Raku Advent Calenda=
r or your very own.</div><div><br></div></div><br><div class=3D"gmail_quote=
"><div dir=3D"ltr" class=3D"gmail_attr">El lun., 9 dic. 2019 a las 3:16, To=
ddAndMargo via perl6-users (&lt;<a href=3D"mailto:perl6-users@perl.org">per=
l6-users@perl.org</a>&gt;) escribi=C3=B3:<br></div><blockquote class=3D"gma=
il_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,2=
04,204);padding-left:1ex">Hi All,<br>
<br>
I have a &quot;grand idea&quot; on how to fix up the documentation<br>
I would like to pitch to the community:<br>
<br>
Raku&#39;s documentation is pretty much unusable for<br>
newbies and regular users do to its culture:<br>
IEEE-eese like &quot;method contains(Cool:D: |c)&quot;<br>
and so on and so forth.=C2=A0 Sometimes a usable<br>
example sneaks through.=C2=A0 It is targeted at<br>
the wrong audience.<br>
<br>
It has been pointed out that the reason why Perl 5&#39;s<br>
perldocs is so much better done that Raku&#39;s is that<br>
Perl 5 has some industry funding behind it and<br>
Raku is a volunteer effort.<br>
<br>
To cope with such, I write my own keepers on<br>
various parts of Raku.=C2=A0 I have posted a couple<br>
of them here.=C2=A0 I am up to 190 of them now.<br>
<br>
So here is my idea.=C2=A0 Since this is a volunteer effort,<br>
lets not loose the value of my own 190 notes and<br>
everyone else&#39;s contributions as well.<br>
<br>
Lets create our own community documentation Wikipedia.<br>
<br>
Make it so any Raku user can wax eloquent on any<br>
part of the documentation.=C2=A0 Have it peer reviewed for<br>
accuracy and content, and then published for all<br>
to use.<br>
<br>
This would shut me up complaining about the IEEE-eese<br>
and give me and other a chance to contribute on<br>
a major scale.=C2=A0 A true community effort.<br>
<br>
And, chuckle, keep the guard dog constructively<br>
employed, instead of coming up his a bazillions<br>
way to say (put to music) &quot;no, No, NO, no no no,<br>
NOT A BUG, NOT OUR PROBLEM, no no no, I don&#39;t<br>
think this applies&quot;.<br>
<br>
Given time, we could have some awesome documentation!<br>
And it would be all in one place, not spread out all<br>
over the Internet.=C2=A0 It would be something we could all<br>
take pride in.<br>
<br>
And those versed in the IEEE-eese can still use<br>
the original documentation.<br>
<br>
-T<br>
</blockquote></div><br clear=3D"all"><br>-- <br><div dir=3D"ltr" class=3D"g=
mail_signature">JJ</div>

--000000000000c936fb0599413f31--
0
jjmerelo
12/9/2019 8:33:14 AM
On 2019-12-09 00:33, JJ Merelo wrote:
> The Raku community has got a community documentation. It's called the 
> official documentation, and it's done by the community. You want to 
> write your own and help yourself and maybe others, there're lots lof 
> places you can do that: dev.to <http://dev.to>, Medium, your own blog. 
> Even the "official" Raku Advent Calendar or your very own.


Spoken by a true guard dog!  :-)

I am speaking of a way to possibly get everyone in
on the act.  And make it official to the Raku site.
No digging around with Google.
0
perl6
12/9/2019 9:32:18 AM
--00000000000018cc7f0599422ca6
Content-Type: text/plain; charset="UTF-8"

On Mon, Dec 9, 2019 at 5:34 PM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-09 00:33, JJ Merelo wrote:
> > The Raku community has got a community documentation. It's called the
> > official documentation, and it's done by the community. You want to
> > write your own and help yourself and maybe others, there're lots lof
> > places you can do that: dev.to <http://dev.to>, Medium, your own blog.
> > Even the "official" Raku Advent Calendar or your very own.
>
>
> Spoken by a true guard dog!  :-)
>


It's rude on a public list to speak that.
There are the real people on the list talking with you, not the dog.
Also please consider Perl blogs for writing:
http://blogs.perl.org/

Regards.





>
> I am speaking of a way to possibly get everyone in
> on the act.  And make it official to the Raku site.
> No digging around with Google.
>

--00000000000018cc7f0599422ca6
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=3D"gmail_quote">=
<div dir=3D"ltr" class=3D"gmail_attr">On Mon, Dec 9, 2019 at 5:34 PM ToddAn=
dMargo via perl6-users &lt;<a href=3D"mailto:perl6-users@perl.org">perl6-us=
ers@perl.org</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" styl=
e=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);paddin=
g-left:1ex">On 2019-12-09 00:33, JJ Merelo wrote:<br>
&gt; The Raku community has got a community documentation. It&#39;s called =
the <br>
&gt; official documentation, and it&#39;s done by the community. You want t=
o <br>
&gt; write your own and help yourself and maybe others, there&#39;re lots l=
of <br>
&gt; places you can do that: <a href=3D"http://dev.to" rel=3D"noreferrer" t=
arget=3D"_blank">dev.to</a> &lt;<a href=3D"http://dev.to" rel=3D"noreferrer=
" target=3D"_blank">http://dev.to</a>&gt;, Medium, your own blog. <br>
&gt; Even the &quot;official&quot; Raku Advent Calendar or your very own.<b=
r>
<br>
<br>
Spoken by a true guard dog!=C2=A0 :-)<br></blockquote><div><br></div><div><=
br></div><div>It&#39;s rude on a public list to speak that.</div><div>There=
 are the real people on the list talking with you, not the dog.</div><div>A=
lso please consider Perl blogs for writing:</div><div><a href=3D"http://blo=
gs.perl.org/">http://blogs.perl.org/</a></div><div><br></div><div>Regards.<=
/div><div><br></div><div><br></div><div><br></div><div>=C2=A0</div><blockqu=
ote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px=
 solid rgb(204,204,204);padding-left:1ex">
<br>
I am speaking of a way to possibly get everyone in<br>
on the act.=C2=A0 And make it official to the Raku site.<br>
No digging around with Google.<br>
</blockquote></div></div>

--00000000000018cc7f0599422ca6--
0
tom
12/9/2019 9:39:19 AM
--0000000000004a635b0599425ac0
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

El lun., 9 dic. 2019 a las 10:34, ToddAndMargo via perl6-users (<
perl6-users@perl.org>) escribi=C3=B3:

> On 2019-12-09 00:33, JJ Merelo wrote:
> > The Raku community has got a community documentation. It's called the
> > official documentation, and it's done by the community. You want to
> > write your own and help yourself and maybe others, there're lots lof
> > places you can do that: dev.to <http://dev.to>, Medium, your own blog.
> > Even the "official" Raku Advent Calendar or your very own.
>
>
> Spoken by a true guard dog!  :-)
>

If I'm a dog, I choose to be a Lab. Mr. Peanutbutter Lab, if anyone asks.

>
> I am speaking of a way to possibly get everyone in
> on the act.  And make it official to the Raku site.
>

You mean, as in an "official documentation"? Well, there's this thing
unimaginatively called "official documentation" at https://docs.raku.org.
Lots of people are volunteering to make it better every single day. It's
not everything to everyone, and it can't possibly be. But there are other
places you can look at, like tutorials, and the whole wide Internet. To
which you can contribute, if you so like.

Cheers

JJ

--0000000000004a635b0599425ac0
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=3D"gmail_quote">=
<div dir=3D"ltr" class=3D"gmail_attr">El lun., 9 dic. 2019 a las 10:34, Tod=
dAndMargo via perl6-users (&lt;<a href=3D"mailto:perl6-users@perl.org">perl=
6-users@perl.org</a>&gt;) escribi=C3=B3:<br></div><blockquote class=3D"gmai=
l_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,20=
4,204);padding-left:1ex">On 2019-12-09 00:33, JJ Merelo wrote:<br>
&gt; The Raku community has got a community documentation. It&#39;s called =
the <br>
&gt; official documentation, and it&#39;s done by the community. You want t=
o <br>
&gt; write your own and help yourself and maybe others, there&#39;re lots l=
of <br>
&gt; places you can do that: <a href=3D"http://dev.to" rel=3D"noreferrer" t=
arget=3D"_blank">dev.to</a> &lt;<a href=3D"http://dev.to" rel=3D"noreferrer=
" target=3D"_blank">http://dev.to</a>&gt;, Medium, your own blog. <br>
&gt; Even the &quot;official&quot; Raku Advent Calendar or your very own.<b=
r>
<br>
<br>
Spoken by a true guard dog!=C2=A0 :-)<br></blockquote><div><br></div><div>I=
f I&#39;m a dog, I choose to be a Lab. Mr. Peanutbutter Lab, if anyone asks=
.. <br></div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0=
..8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
I am speaking of a way to possibly get everyone in<br>
on the act.=C2=A0 And make it official to the Raku site.<br></blockquote><d=
iv><br></div><div>You mean, as in an &quot;official documentation&quot;? We=
ll, there&#39;s this thing unimaginatively called &quot;official documentat=
ion&quot; at <a href=3D"https://docs.raku.org">https://docs.raku.org</a>. L=
ots of people are volunteering to make it better every single day. It&#39;s=
 not everything to everyone, and it can&#39;t possibly be. But there are ot=
her places you can look at, like tutorials, and the whole wide Internet. To=
 which you can contribute, if you so like.<br></div><div><br></div><div>Che=
ers</div><div><br></div><div>JJ<br></div></div><br></div>

--0000000000004a635b0599425ac0--
0
jjmerelo
12/9/2019 9:52:13 AM
On 2019-12-09 01:52, JJ Merelo wrote:
>=20
>=20
> El lun., 9 dic. 2019 a las 10:34, ToddAndMargo via perl6-users=20
> (<perl6-users@perl.org <mailto:perl6-users@perl.org>>) escribi=C3=B3:
>=20
>     On 2019-12-09 00:33, JJ Merelo wrote:
>      > The Raku community has got a community documentation. It's calle=
d
>     the
>      > official documentation, and it's done by the community. You want=
 to
>      > write your own and help yourself and maybe others, there're lots=
 lof
>      > places you can do that: dev.to <http://dev.to> <http://dev.to>,
>     Medium, your own blog.
>      > Even the "official" Raku Advent Calendar or your very own.
>=20
>=20
>     Spoken by a true guard dog!=C2=A0 :-)
>=20
>=20
> If I'm a dog, I choose to be a Lab. Mr. Peanutbutter Lab, if anyone ask=
s.
>=20
>=20
>     I am speaking of a way to possibly get everyone in
>     on the act.=C2=A0 And make it official to the Raku site.
>=20
>=20
> You mean, as in an "official documentation"? Well, there's this thing=20
> unimaginatively called "official documentation" at=20
> https://docs.raku.org. Lots of people are volunteering to make it bette=
r=20
> every single day. It's not everything to everyone, and it can't possibl=
y=20
> be. But there are other places you can look at, like tutorials, and the=
=20
> whole wide Internet. To which you can contribute, if you so like.
>=20
> Cheers
>=20
> JJ
>=20


JJ,

The "Community" you speak of it a collection of extremely
brilliant programmers.  I will call them the "Community
of Developers".  They are badly overworked and have
prioritized what they can volunteer for.  Because
of this, the documentation takes are real hit: its
would make a cryptologist blush and the IEEE extremely
proud.

Your job as a Peanutbutter Lab (junkyard dog) is to
protect them from frivolous input from the likes of,
well, me.

The community I am speaking of is the the rest of us,
which I will call the Rakoons.  This does include the
"Community of Developers" but mainly its includes all
Raku programmers interested in making Raku's documentation
better.

And it included a request list, so things would be
prioritized by need.  You might even have an automatic
mailing go our to Rakoon volunteers to pick up such
requests.

My Grand Idea would be a real boom for us Rakoons.
I can tell it is already driving you nuts.  With
love and understanding and a few dog biscuits, you
will survive.  I promise!

-T
0
perl6
12/9/2019 10:23:12 AM
--0000000000006688ec0599432296
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

El lun., 9 dic. 2019 a las 11:26, ToddAndMargo via perl6-users (<
perl6-users@perl.org>) escribi=C3=B3:

> On 2019-12-09 01:52, JJ Merelo wrote:
> >
> >
> > El lun., 9 dic. 2019 a las 10:34, ToddAndMargo via perl6-users
> > (<perl6-users@perl.org <mailto:perl6-users@perl.org>>) escribi=C3=B3:
> >
> >     On 2019-12-09 00:33, JJ Merelo wrote:
> >      > The Raku community has got a community documentation. It's calle=
d
> >     the
> >      > official documentation, and it's done by the community. You want
> to
> >      > write your own and help yourself and maybe others, there're lots
> lof
> >      > places you can do that: dev.to <http://dev.to> <http://dev.to>,
> >     Medium, your own blog.
> >      > Even the "official" Raku Advent Calendar or your very own.
> >
> >
> >     Spoken by a true guard dog!  :-)
> >
> >
> > If I'm a dog, I choose to be a Lab. Mr. Peanutbutter Lab, if anyone ask=
s.
> >
> >
> >     I am speaking of a way to possibly get everyone in
> >     on the act.  And make it official to the Raku site.
> >
> >
> > You mean, as in an "official documentation"? Well, there's this thing
> > unimaginatively called "official documentation" at
> > https://docs.raku.org. Lots of people are volunteering to make it
> better
> > every single day. It's not everything to everyone, and it can't possibl=
y
> > be. But there are other places you can look at, like tutorials, and the
> > whole wide Internet. To which you can contribute, if you so like.
> >
> > Cheers
> >
> > JJ
> >
>
>
> JJ,
>
> The "Community" you speak of it a collection of extremely
> brilliant programmers.  I will call them the "Community
> of Developers".  They are badly overworked and have
> prioritized what they can volunteer for.  Because
> of this, the documentation takes are real hit: its
> would make a cryptologist blush and the IEEE extremely
> proud.
>

As an ACM member, I take offense at this.

And I'm not really going to answer to the rest. It's simply not true. You
don't understand lots of things that are there, fair enough. You don't need
to. I always tell my students: "keep trying, and ask around when you're
lost". They never, however, convert their inability in understanding
something in a judgment on the quality of the material used for learning,
which has probably been evolved through generations of other fellow
students, so it's as good as it needs to be.

You don't want to learn through the documentation, again, fair enough. Use
StackOverflow, books, whatever. Your call. I get the documentation needs
improvement. There are ~300 issues that need to be solved. We do what we
can. But let's not throw the baby with the bathwater. Let's keep improving
the official documentation, and let's try to make it as good as possible
for the majority of developers out there.


> Your job as a Peanutbutter Lab (junkyard dog) is to
> protect them from frivolous input from the likes of,
> well, me.
>
> No, it's not. I simply tried to direct you to raise an issue to where it
would actually be heard by the people that maintain that. You don't want to
listen, your call. But check if it's done any good in the first place you
raised the issue, or where it was moved. You don't want to listen to what I
said, you want stuff your way or the highway. Fair enough, I'll not try to
help you again. But if nobody answers your issue which you want to do your
own way (for instance, proposing "solutions" in a mailing list instead of
raising issues in the specific places where they can be addressed), don't
say we didn't warn you.

The community I am speaking of is the the rest of us,
> which I will call the Rakoons.  This does include the
> "Community of Developers" but mainly its includes all
> Raku programmers interested in making Raku's documentation
> better.
>

The rest of us (remember, we weren't born working with the documentation)
do not want you to speak for, well, the rest of us. We all have a voice,
and we also listen to everyone. We don't want anyone, however, to speak for
us. So please don't do that.



> And it included a request list, so things would be
> prioritized by need.  You might even have an automatic
> mailing go our to Rakoon volunteers to pick up such
> requests.
>

As in, say, the automatic email everyone in the Raku team gets when anyone
raises an issue in any of the repositories?


> My Grand Idea would be a real boom for us Rakoons.
>

No, it wouldn't, and it will not. You want to publish your "keepers" which
are much better than the documentation, by all means do that. Speak for
yourself, not for others.

Cheers

JJ

--0000000000006688ec0599432296
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=3D"gmail_quote">=
<div dir=3D"ltr" class=3D"gmail_attr">El lun., 9 dic. 2019 a las 11:26, Tod=
dAndMargo via perl6-users (&lt;<a href=3D"mailto:perl6-users@perl.org">perl=
6-users@perl.org</a>&gt;) escribi=C3=B3:<br></div><blockquote class=3D"gmai=
l_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,20=
4,204);padding-left:1ex">On 2019-12-09 01:52, JJ Merelo wrote:<br>
&gt; <br>
&gt; <br>
&gt; El lun., 9 dic. 2019 a las 10:34, ToddAndMargo via perl6-users <br>
&gt; (&lt;<a href=3D"mailto:perl6-users@perl.org" target=3D"_blank">perl6-u=
sers@perl.org</a> &lt;mailto:<a href=3D"mailto:perl6-users@perl.org" target=
=3D"_blank">perl6-users@perl.org</a>&gt;&gt;) escribi=C3=B3:<br>
&gt; <br>
&gt;=C2=A0 =C2=A0 =C2=A0On 2019-12-09 00:33, JJ Merelo wrote:<br>
&gt;=C2=A0 =C2=A0 =C2=A0 &gt; The Raku community has got a community docume=
ntation. It&#39;s called<br>
&gt;=C2=A0 =C2=A0 =C2=A0the<br>
&gt;=C2=A0 =C2=A0 =C2=A0 &gt; official documentation, and it&#39;s done by =
the community. You want to<br>
&gt;=C2=A0 =C2=A0 =C2=A0 &gt; write your own and help yourself and maybe ot=
hers, there&#39;re lots lof<br>
&gt;=C2=A0 =C2=A0 =C2=A0 &gt; places you can do that: <a href=3D"http://dev=
..to" rel=3D"noreferrer" target=3D"_blank">dev.to</a> &lt;<a href=3D"http://=
dev.to" rel=3D"noreferrer" target=3D"_blank">http://dev.to</a>&gt; &lt;<a h=
ref=3D"http://dev.to" rel=3D"noreferrer" target=3D"_blank">http://dev.to</a=
>&gt;,<br>
&gt;=C2=A0 =C2=A0 =C2=A0Medium, your own blog.<br>
&gt;=C2=A0 =C2=A0 =C2=A0 &gt; Even the &quot;official&quot; Raku Advent Cal=
endar or your very own.<br>
&gt; <br>
&gt; <br>
&gt;=C2=A0 =C2=A0 =C2=A0Spoken by a true guard dog!=C2=A0 :-)<br>
&gt; <br>
&gt; <br>
&gt; If I&#39;m a dog, I choose to be a Lab. Mr. Peanutbutter Lab, if anyon=
e asks.<br>
&gt; <br>
&gt; <br>
&gt;=C2=A0 =C2=A0 =C2=A0I am speaking of a way to possibly get everyone in<=
br>
&gt;=C2=A0 =C2=A0 =C2=A0on the act.=C2=A0 And make it official to the Raku =
site.<br>
&gt; <br>
&gt; <br>
&gt; You mean, as in an &quot;official documentation&quot;? Well, there&#39=
;s this thing <br>
&gt; unimaginatively called &quot;official documentation&quot; at <br>
&gt; <a href=3D"https://docs.raku.org" rel=3D"noreferrer" target=3D"_blank"=
>https://docs.raku.org</a>. Lots of people are volunteering to make it bett=
er <br>
&gt; every single day. It&#39;s not everything to everyone, and it can&#39;=
t possibly <br>
&gt; be. But there are other places you can look at, like tutorials, and th=
e <br>
&gt; whole wide Internet. To which you can contribute, if you so like.<br>
&gt; <br>
&gt; Cheers<br>
&gt; <br>
&gt; JJ<br>
&gt; <br>
<br>
<br>
JJ,<br>
<br>
The &quot;Community&quot; you speak of it a collection of extremely<br>
brilliant programmers.=C2=A0 I will call them the &quot;Community<br>
of Developers&quot;.=C2=A0 They are badly overworked and have<br>
prioritized what they can volunteer for.=C2=A0 Because<br>
of this, the documentation takes are real hit: its<br>
would make a cryptologist blush and the IEEE extremely<br>
proud.<br></blockquote><div><br></div><div>As an ACM member, I take offense=
 at this.</div><div><br></div><div>And I&#39;m not really going to answer t=
o the rest. It&#39;s simply not true. You don&#39;t understand lots of thin=
gs that are there, fair enough. You don&#39;t need to. I always tell my stu=
dents: &quot;keep trying, and ask around when you&#39;re lost&quot;. They n=
ever, however, convert their inability in understanding something in a judg=
ment on the quality of the material used for learning, which has probably b=
een evolved through generations of other fellow students, so it&#39;s as go=
od as it needs to be. <br></div><div><br></div><div>You don&#39;t want to l=
earn through the documentation, again, fair enough. Use StackOverflow, book=
s, whatever. Your call. I get the documentation needs improvement. There ar=
e ~300 issues that need to be solved. We do what we can. But let&#39;s not =
throw the baby with the bathwater. Let&#39;s keep improving the official do=
cumentation, and let&#39;s try to make it as good as possible for the major=
ity of developers out there. <br></div><div><br></div><blockquote class=3D"=
gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(20=
4,204,204);padding-left:1ex">
<br>
Your job as a Peanutbutter Lab (junkyard dog) is to<br>
protect them from frivolous input from the likes of,<br>
well, me.<br>
<br></blockquote><div>No, it&#39;s not. I simply tried to direct you to rai=
se an issue to where it would actually be heard by the people that maintain=
 that. You don&#39;t want to listen, your call. But check if it&#39;s done =
any good in the first place you raised the issue, or where it was moved. Yo=
u don&#39;t want to listen to what I said, you want stuff your way or the h=
ighway. Fair enough, I&#39;ll not try to help you again. But if nobody answ=
ers your issue which you want to do your own way (for instance, proposing &=
quot;solutions&quot; in a mailing list instead of raising issues in the spe=
cific places where they can be addressed), don&#39;t say we didn&#39;t warn=
 you.<br></div><div> <br></div><blockquote class=3D"gmail_quote" style=3D"m=
argin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left=
:1ex">
The community I am speaking of is the the rest of us,<br>
which I will call the Rakoons.=C2=A0 This does include the<br>
&quot;Community of Developers&quot; but mainly its includes all<br>
Raku programmers interested in making Raku&#39;s documentation<br>
better.<br></blockquote><div><br></div><div>The rest of us (remember, we we=
ren&#39;t born working with the documentation) do not want you to speak for=
, well, the rest of us. We all have a voice, and we also listen to everyone=
.. We don&#39;t want anyone, however, to speak for us. So please don&#39;t d=
o that.</div><div><br></div><div> <br></div><blockquote class=3D"gmail_quot=
e" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204)=
;padding-left:1ex">
<br>
And it included a request list, so things would be<br>
prioritized by need.=C2=A0 You might even have an automatic<br>
mailing go our to Rakoon volunteers to pick up such<br>
requests.<br></blockquote><div><br></div><div>As in, say, the automatic ema=
il everyone in the Raku team gets when anyone raises an issue in any of the=
 repositories?</div><div> <br></div><blockquote class=3D"gmail_quote" style=
=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding=
-left:1ex">
<br>
My Grand Idea would be a real boom for us Rakoons.<br></blockquote><div><br=
></div><div>No, it wouldn&#39;t, and it will not. You want to publish your =
&quot;keepers&quot; which are much better than the documentation, by all me=
ans do that. Speak for yourself, not for others. <br></div></div><div><br><=
/div><div>Cheers</div><div><br></div><div>JJ<br></div></div>

--0000000000006688ec0599432296--
0
jjmerelo
12/9/2019 10:48:11 AM
> On 9 Dec 2019, at 10:32, ToddAndMargo via perl6-users =
<perl6-users@perl.org> wrote:
> On 2019-12-09 00:33, JJ Merelo wrote:
>> The Raku community has got a community documentation. It's called the =
official documentation, and it's done by the community. You want to =
write your own and help yourself and maybe others, there're lots lof =
places you can do that: dev.to <http://dev.to>, Medium, your own blog. =
Even the "official" Raku Advent Calendar or your very own.
> Spoken by a true guard dog!  :-)

Not funny at all.  I'm very close to put you in my *plonk* category.=
0
liz
12/9/2019 11:47:07 AM
On 2019-12-09 01:39, Tom Blackwood wrote:
> It's rude on a public list to speak that.

Did you seriously think I was calling him a
real dog (canine)?

JJ! I do not think you are a canine.

-T
0
perl6
12/9/2019 1:45:36 PM
On 2019-12-09 02:48, JJ Merelo wrote:
> And I'm not really going to answer to the rest. It's simply not true. 
> You don't understand lots of things that are there, fair enough. You 
> don't need to. I always tell my students: "keep trying, and ask around 
> when you're lost". They never, however, convert their inability in 
> understanding something in a judgment on the quality of the material 
> used for learning, which has probably been evolved through generations 
> of other fellow students, so it's as good as it needs to be.


> 
> You don't want to learn through the documentation, again, fair enough. 
> Use StackOverflow, books, whatever. Your call. I get the documentation 
> needs improvement. There are ~300 issues that need to be solved. We do 
> what we can. But let's not throw the baby with the bathwater. Let's keep 
> improving the official documentation, and let's try to make it as good 
> as possible for the majority of developers out there.

What school did you go to?  Students rate good and bad
teachers, good and bad material ALL-THE-TIME.

When I was in college, I actually got rid of two bad
teachers.  Ya, I am a bit of jerk over teachers that
take my money and don't do their jobs.

The major issue with the documentation is that it targets the
wrong audience.  Those that understand the cryptography,
don't' need the documentation.  They already know what
it is suppose to say.

Did you see my post of ".contains".  I took the cryptography
apart and explained what the heck each part of it meant.

Do you think any of that actually helped me use ".contains"?

Do you think I even remembered what it meant?

When I have an issue, I first go to the docs.  I have
to shake my head over how unnecessarily difficult they
have made things to understand.   If I can't pick it out
from any of their examples, then it is off to Google.

Perl 5 is not this way.  Raku should not be either.  And
the reason I keep beating a dead horse.

I am not trying to throw the baby out with the bath water.
I am trying to get more folks involved.

As long as the Doc's culture is "the answer is intuitive
obvious and let to the student to figure out", the docs
are going to remain difficult to use by standard programmers.

Before the docs can become useful, the intended audiance must
be changed.

-T

I don't think you are a canine.





-- 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Computers are like air conditioners.
They malfunction when you open windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0
perl6
12/9/2019 2:06:28 PM
On 2019-12-09 02:48, JJ Merelo wrote:
> No, it's not. I simply tried to direct you to raise an issue to where it 
> would actually be heard by the people that maintain that.

For you that don't know what JJ and I are talking
about here, you can read it over at

zef requires git
https://github.com/rakudo/star/issues/145


Hi JJ,

This is a bug I reported over on Fedora:

WoeUSB crashes on exit
https://bugzilla.redhat.com/show_bug.cgi?id=1773142

    #2:
    Hi Todd,

    I am the maintainer of the WoeUSB package but
    I'm not involved with any of the development.
    Please look for an existing issue or file a
    new one at https://github.com/slacka/WoeUSB
    to get attention from the developers.

    #3:
    Hi Matt,

    Thank you for the link.  I seldom can figure
    out who "upstream" is.

    Companion bug: https://github.com/slacka/WoeUSB/issues/288


Matt told me where to go and I immediately opened the issue
"upstream" and reported back what that bug was so others
could find it in searches.  Fedora is very professional
this way.

You did not do this.  You instead fobbed me off with
what amounted to "not my problem".  I even asked you
where "upstream" was.  Crickets and frogs.  Coke
stepped in a solved the issue.

This is why I referred to you as a guard dog.  (Note
to everyone, I do not think he is an actual dog.)
It is pretty hard to get past you.  You do a great
job of protecting the developers from us Riff-Raff.

-T
0
perl6
12/9/2019 2:21:39 PM
> On 9 Dec 2019, at 14:45, ToddAndMargo via perl6-users =
<perl6-users@perl.org> wrote:
> On 2019-12-09 01:39, Tom Blackwood wrote:
>> It's rude on a public list to speak that.
> Did you seriously think I was calling him a real dog (canine)?

So what did you intend to convey with the use of the word "guard dog"?  =
That he is a nice, hard working volunteer?  I think not.  There are =
other words to describe that.=
0
liz
12/9/2019 2:23:21 PM
On 2019-12-09 03:47, Elizabeth Mattijsen wrote:
>> On 9 Dec 2019, at 10:32, ToddAndMargo via perl6-users <perl6-users@perl.org> wrote:
>> On 2019-12-09 00:33, JJ Merelo wrote:
>>> The Raku community has got a community documentation. It's called the official documentation, and it's done by the community. You want to write your own and help yourself and maybe others, there're lots lof places you can do that: dev.to <http://dev.to>, Medium, your own blog. Even the "official" Raku Advent Calendar or your very own.
>> Spoken by a true guard dog!  :-)
> 
> Not funny at all.  I'm very close to put you in my *plonk* category.
> 

For some odd reason, some folks thought I was calling
him an actual dog (canine).  Would you have been
similarly offended if I had called him a "gatekeeper"?

I actually think JJ is a pretty great guy, except when
he is guarding the gates.

Is English your first language?
0
perl6
12/9/2019 2:26:38 PM
--0000000000006efe2d059946656b
Content-Type: text/plain; charset="UTF-8"

I find both the implications of "guard dog" and "gatekeeper" unfair ways to
talk about anyone on the community especially JJ.


On Mon, 9 Dec 2019, 14:38 ToddAndMargo via perl6-users, <
perl6-users@perl.org> wrote:

> On 2019-12-09 03:47, Elizabeth Mattijsen wrote:
> >> On 9 Dec 2019, at 10:32, ToddAndMargo via perl6-users <
> perl6-users@perl.org> wrote:
> >> On 2019-12-09 00:33, JJ Merelo wrote:
> >>> The Raku community has got a community documentation. It's called the
> official documentation, and it's done by the community. You want to write
> your own and help yourself and maybe others, there're lots lof places you
> can do that: dev.to <http://dev.to>, Medium, your own blog. Even the
> "official" Raku Advent Calendar or your very own.
> >> Spoken by a true guard dog!  :-)
> >
> > Not funny at all.  I'm very close to put you in my *plonk* category.
> >
>
> For some odd reason, some folks thought I was calling
> him an actual dog (canine).  Would you have been
> similarly offended if I had called him a "gatekeeper"?
>
> I actually think JJ is a pretty great guy, except when
> he is guarding the gates.
>
> Is English your first language?
>

--0000000000006efe2d059946656b
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"auto">I find both the implications of &quot;guard dog&quot; and=
 &quot;gatekeeper&quot; unfair ways to talk about anyone on the community e=
specially JJ.<div dir=3D"auto"><br></div></div><br><div class=3D"gmail_quot=
e"><div dir=3D"ltr" class=3D"gmail_attr">On Mon, 9 Dec 2019, 14:38 ToddAndM=
argo via perl6-users, &lt;<a href=3D"mailto:perl6-users@perl.org">perl6-use=
rs@perl.org</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=
=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 2019-=
12-09 03:47, Elizabeth Mattijsen wrote:<br>
&gt;&gt; On 9 Dec 2019, at 10:32, ToddAndMargo via perl6-users &lt;<a href=
=3D"mailto:perl6-users@perl.org" target=3D"_blank" rel=3D"noreferrer">perl6=
-users@perl.org</a>&gt; wrote:<br>
&gt;&gt; On 2019-12-09 00:33, JJ Merelo wrote:<br>
&gt;&gt;&gt; The Raku community has got a community documentation. It&#39;s=
 called the official documentation, and it&#39;s done by the community. You=
 want to write your own and help yourself and maybe others, there&#39;re lo=
ts lof places you can do that: <a href=3D"http://dev.to" rel=3D"noreferrer =
noreferrer" target=3D"_blank">dev.to</a> &lt;<a href=3D"http://dev.to" rel=
=3D"noreferrer noreferrer" target=3D"_blank">http://dev.to</a>&gt;, Medium,=
 your own blog. Even the &quot;official&quot; Raku Advent Calendar or your =
very own.<br>
&gt;&gt; Spoken by a true guard dog!=C2=A0 :-)<br>
&gt; <br>
&gt; Not funny at all.=C2=A0 I&#39;m very close to put you in my *plonk* ca=
tegory.<br>
&gt; <br>
<br>
For some odd reason, some folks thought I was calling<br>
him an actual dog (canine).=C2=A0 Would you have been<br>
similarly offended if I had called him a &quot;gatekeeper&quot;?<br>
<br>
I actually think JJ is a pretty great guy, except when<br>
he is guarding the gates.<br>
<br>
Is English your first language?<br>
</blockquote></div>

--0000000000006efe2d059946656b--
0
simon
12/9/2019 2:41:40 PM
On 2019-12-09 06:23, Elizabeth Mattijsen wrote:
>> On 9 Dec 2019, at 14:45, ToddAndMargo via perl6-users <perl6-users@perl.org> wrote:
>> On 2019-12-09 01:39, Tom Blackwood wrote:
>>> It's rude on a public list to speak that.
>> Did you seriously think I was calling him a real dog (canine)?
> 
> So what did you intend to convey with the use of the word "guard dog"?  That he is a nice, hard working volunteer?  I think not.  There are other words to describe that.
> 

I meant that he protects the developers for frivolous
input from the general public, such as me.  A "Guard
Dog" protects you from threats.  The developers are
very busy.

JJ is a great guy by the way.  He is just a little too protective when 
is on guard duty.  ("Guard Duty" means
he is in protective duty, not that he is a prison guard.)

Is English your first language?  See I have used
language twice that you have objected to.  Believe me,
when I want to be offensive, no one from any language
will miss it.
0
perl6
12/9/2019 2:47:02 PM
On 2019-12-09 06:41, Simon Proctor wrote:
> I find both the implications of "guard dog" and "gatekeeper" unfair ways 
> to talk about anyone on the community especially JJ.

Hi Simon,

JJ is indeed a great guy.  That is not up for debate.

He is just a little too protective when he is on duty.
"guard dog" and "gatekeeper" are meant to describe
this.  They are not meant to call him a dog or a piece
of iron works.

If I intend to be offensive, believe me, not matter
what language you speak, believe me you will not
misunderstand me.

Is English your first language?

-T
0
perl6
12/9/2019 2:51:32 PM

> On 9 Dec 2019, at 15:26, ToddAndMargo via perl6-users =
<perl6-users@perl.org> wrote:
>=20
> On 2019-12-09 03:47, Elizabeth Mattijsen wrote:
>>> On 9 Dec 2019, at 10:32, ToddAndMargo via perl6-users =
<perl6-users@perl.org> wrote:
>>> On 2019-12-09 00:33, JJ Merelo wrote:
>>>> The Raku community has got a community documentation. It's called =
the official documentation, and it's done by the community. You want to =
write your own and help yourself and maybe others, there're lots lof =
places you can do that: dev.to <http://dev.to>, Medium, your own blog. =
Even the "official" Raku Advent Calendar or your very own.
>>> Spoken by a true guard dog!  :-)
>> Not funny at all.  I'm very close to put you in my *plonk* category.
>=20
> For some odd reason, some folks thought I was calling
> him an actual dog (canine).  Would you have been
> similarly offended if I had called him a "gatekeeper"?

If you call someone a dog, it is most likely you intended the "an =
unpleasant, contemptible, or wicked man" meaning.  Check your =
dictionary:

dog | d=C9=92=C9=A1 |=20
noun
1 a domesticated carnivorous mammal that typically has a long snout, an =
acute sense of smell, non-retractable claws, and a barking, howling, or =
whining voice.=20
Canis familiaris, family Canidae (the dog family); probably domesticated =
from the wolf in the Mesolithic period. The dog family also includes the =
wolves, coyotes, jackals, and foxes.
=E2=80=A2 a wild animal of the dog family.=20
=E2=80=A2 the male of an animal of the dog family, or of some other =
mammals such as the otter: [as modifier] :  a dog fox.=20
=E2=80=A2 (the dogs) British informal greyhound racing: a night at the =
dogs.=20
2 informal an unpleasant, contemptible, or wicked man: he wasinterrupted =
by cries of =E2=80=98dirty dog!=E2=80=99 | come out, Michael, you dog!=20=

=E2=80=A2 [with adjective] dated used to refer to a person of a =
specified kind in a tone of playful reproof, commiseration, or =
congratulation: your historian is a dull dog | you lucky dog!=20
=E2=80=A2 used to refer to someone who is abject or miserable, =
especially because they have been treated harshly: I make him work like =
a dog| Rab was treated like a dog.=20
=E2=80=A2 informal, offensive an unattractive woman.=20
=E2=80=A2 Australian/NZ informal an informer or traitor: one day she's =
going to turn dog on you.=20
=E2=80=A2 informal, chiefly North American a thing of poor quality: a =
dog of afilm.=20
=E2=80=A2 informal a horse that is slow or difficult to handle.=20
3 used in names of dogfishes, e.g. sandy dog, spur-dog.=20
4 a mechanical device for gripping.=20
5 (dogs) North American informal feet.=20
6 (dogs) Horse Racing, US barriers used to keep horses off a particular =
part of the track.


> Is English your first language?

No, is it yours?=
0
liz
12/9/2019 3:00:52 PM
--0000000000000fea720599470e0e
Content-Type: text/plain; charset="UTF-8"

On Mon, Dec 9, 2019 at 10:08 AM Simon Proctor <simon.proctor@gmail.com>
wrote:

> I find both the implications of "guard dog" and "gatekeeper" unfair ways
> to talk about anyone on the community especially JJ.
>

I understand that the intent was derogatory, but I would encourage JJ to
take it as a compliment.

He is a beloved protector (as well as producer) of valued assets,
faithfully preventing their despoilage by those would seek to degrade or
otherwise damage them.

Curt

--0000000000000fea720599470e0e
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><div class=3D"gmail_quote"><div=
 dir=3D"ltr" class=3D"gmail_attr">On Mon, Dec 9, 2019 at 10:08 AM Simon Pro=
ctor &lt;<a href=3D"mailto:simon.proctor@gmail.com">simon.proctor@gmail.com=
</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"margin:=
0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">=
<div dir=3D"auto">I find both the implications of &quot;guard dog&quot; and=
 &quot;gatekeeper&quot; unfair ways to talk about anyone on the community e=
specially JJ.</div></blockquote><div><br></div><div>I understand that the i=
ntent was derogatory, but I would encourage JJ to take it as a compliment.<=
/div><div><br></div><div>He is a beloved protector (as well as producer) of=
 valued assets, faithfully preventing their despoilage by those would seek =
to degrade or otherwise damage them.</div><div><br></div><div>Curt</div><di=
v><br></div></div></div>

--0000000000000fea720599470e0e--
0
curt
12/9/2019 3:28:49 PM
On 12/9/2019 6:06 AM, ToddAndMargo via perl6-users wrote:
> What school did you go to?  Students rate good and bad
> teachers, good and bad material ALL-THE-TIME.

This is a function they are entitled to exercise because they are paying 
the teachers.  As you yourself said:

> When I was in college, I actually got rid of two bad
> teachers.  Ya, I am a bit of jerk over teachers that
> take my money and don't do their jobs.

If you're trying to get rid of the people who write Raku documentation 
(who, contrary to your labeling, are not teachers but developers, and 
either way, unpaid), you're making fine progress.

Your repeated questioning of Liz's native language as a diversion from 
your dissembling about use of derogatory language as though there were 
no difference between connotative and denotative terms serves only to 
alienate you from people who have expended enormous effort to help you.

If you really don't understand the connotations of referring to someone 
as a dog then at least understand that it is offensive to most people 
and expend the necessary effort to learn how to conduct yourself in a 
community of volunteers.

The reference documentation is for reference.  You want tutorials. 
That's a different animal, and exists for Raku mostly in the form of 
books and e-books which you stated you do not want to study.

> The major issue with the documentation is that it targets the
> wrong audience.  Those that understand the cryptography,
> don't' need the documentation.  They already know what
> it is suppose to say.

Developers need reminders, in the most succinct form, to minimize time, 
of data that they should not need to memorize.  The documentation 
satisfies that need in the same way that a phone book satisfies the need 
to look up someone's number.  The phone book is not bloated with 
explanations of each person's favorite food or the history of the phone 
company.

Your 'keeper' documents sound like they should be shared with others who 
may be in the same situation as you.  Please follow the suggestions for 
how to do that so you can see how they are received.

----
Peter Scott
0
peter
12/9/2019 6:48:18 PM
On 2019-12-09 10:48, Peter Scott wrote:
> On 12/9/2019 6:06 AM, ToddAndMargo via perl6-users wrote:
>> What school did you go to?=C2=A0 Students rate good and bad
>> teachers, good and bad material ALL-THE-TIME.
>=20
> This is a function they are entitled to exercise because they are payin=
g=20
> the teachers.=C2=A0 As you yourself said:

Hi Peter,

My parents were great believers in education.  They just did
not believe in paying for it.  I put myself through college.

>=20
>> When I was in college, I actually got rid of two bad
>> teachers.=C2=A0 Ya, I am a bit of jerk over teachers that
>> take my money and don't do their jobs.
>=20
> If you're trying to get rid of the people who write Raku documentation =

> (who, contrary to your labeling, are not teachers but developers, and=20
> either way, unpaid), you're making fine progress.

Oh good lord no.  I am not trying to get anyone fired!  I
am trying to get the docs written for the general user, not
the developers, who do not need them anyway.  I am
trying to get the target audience changed.

>=20
> Your repeated questioning of Liz's native language as a diversion from =

> your dissembling about use of derogatory language as though there were =

> no difference between connotative and denotative terms serves only to=20
> alienate you from people who have expended enormous effort to help you.=


The reason shy I asked her about English being her native language was=20
because she (and you) mistook my description
of JJ being overprotective as being derogatory.  I was not.

Alienating JJ would be a really stupid move, especially
since I really like the guy and respect his technical
opinions.

I rather suspect Liz did not answer my question because
she rather want to think I was making an insult.  But
I will never know.

>=20
> If you really don't understand the connotations of referring to someone=
=20
> as a dog then at least understand that it is offensive to most people=20
> and expend the necessary effort to learn how to conduct yourself in a=20
> community of volunteers.

This is getting ridiculous.

I was not calling him a dog.  I was calling him
over protective.  "Gaurd dog" is a figure of speech.

And by the way, speaking of a dog gnawing on a bone, (I
am not calling you a dog, that was also a figure of speech
to demonstrate to you why I was not calling JJ a dog),
as soon as I found out some folks mistook me calling
JJ a canine or a piece of iron work, I made it perfectly
clear I was not.  JJ is a great guy.  Alienating him
would be a pretty stupid move on my part.

If you keep insisting I was calling JJ a canine, that is
on you, not me.

Just an aside, we Yanks love our dogs.  Apparently,
other parts of the world do not.  I must remember that.

JJ himself said if he was a dog, he be a "Peanut butter
Lab".  For those of you who do not love dogs, JJ just
described himself as a sweet loving spirit.  Sneaky
of him, don't you think?  (Well done JJ, if you are
reading this.)

JJ did not call himself a dog anymore than I did.  Both of
us were using "figures of speech".  JJ is a petty good
guy, maybe not as loving and sweet as a Lab, but
he could be close.

>=20
> The reference documentation is for reference.=C2=A0 You want tutorials.=
=20
> That's a different animal, and exists for Raku mostly in the form of=20
> books and e-books which you stated you do not want to study.

Geez, look at Perldocs.  I want sometime like that.

>=20
>> The major issue with the documentation is that it targets the
>> wrong audience.=C2=A0 Those that understand the cryptography,
>> don't' need the documentation.=C2=A0 They already know what
>> it is suppose to say.
>=20
> Developers need reminders, in the most succinct form, to minimize time,=
=20
> of data that they should not need to memorize.=C2=A0 The documentation =

> satisfies that need in the same way that a phone book satisfies the nee=
d=20
> to look up someone's number.=C2=A0 The phone book is not bloated with=20
> explanations of each person's favorite food or the history of the phone=
=20
> company.

You just criticized putting the signature in the docs.

As your reference goes, your look up a person's phone number,
then if you want more information, then you call them.
You start small and work your way up.

The docs should follow your phone book example.  Here
is what the item does.  You want more information
(the signatures or anything else), go get it here.

I don't think you intended me to take your phone
book example that way though.  The signatures
are putting the cart before the horse.

That was another figure of speech by the way.  I am
not calling anyone or anything a wagon or a farm
animal.

Speaking of starting small and working your way up.
The signatures are akin to telling someone who only
wants to learn how to add 2 and 2 that he first has to
learn how to do a Fast Fourier transform.  (I am
not calling anyone a Fast Fourier transform!)

I want the docs to be refocused on the users.

>=20
> Your 'keeper' documents sound like they should be shared with others wh=
o=20
> may be in the same situation as you.=C2=A0 Please follow the suggestion=
s for=20
> how to do that so you can see how they are received.
>=20
> ----
> Peter Scott

A capitol idea.  This is why I am positing a Wikipedia
style reference where such things can be posted, peer
reviewed, and used by others.  If you want ever more detail, there are=20
books, as many have stated.

As for when I will post my keepers the here, it depends
on if someone asks a questions pertaining to one I have
written on.  Or I just happen to think I did a nice
jobs on one and would like to share it. Most are
rather blunt, to the point, and are written specifically
for me.  They are mainly my reminders.

You have a subject you want me to look and see if I
have written on it?

Thank you for your forbearance (not calling you a bear).

-T

--=20
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Computers are like air conditioners.
They malfunction when you open windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0
perl6
12/10/2019 3:46:21 AM
On 2019-12-09 07:28, Curt Tilmes wrote:
> 
> On Mon, Dec 9, 2019 at 10:08 AM Simon Proctor <simon.proctor@gmail.com 
> <mailto:simon.proctor@gmail.com>> wrote:
> 
>     I find both the implications of "guard dog" and "gatekeeper" unfair
>     ways to talk about anyone on the community especially JJ.
> 
> 
> I understand that the intent was derogatory, but I would encourage JJ to 
> take it as a compliment.

No it was not.  Guard Dog and Gate Keeper are both figures of speech. 
It means he is over protective.  Please stop putting
words in my mouth, especially after I can clarified them to
an extreme extent

> 
> He is a beloved protector (as well as producer) of valued assets, 

Would a "Peanut Lab" describe that quality?  I can't wait
for folks to come out and tell me I am calling him a dog again.

For those of your that do not love dogs, as we Yanks do,
when JJ said if he was a dog, he'd be a Peanutbutter Lab,
he just describes himself as a sweet and loving spirit,
not a  actual dog.  That is why I teased him back about
being a Junkyard dog (look it up).  Again, not calling
him an actual dog.

And after the great extent I have gone to clarify what I
meant, if you or anyone else still thinks I called him an actual dog 
(canine), then it is on you and not me.

> faithfully preventing their despoilage by those would seek to degrade or 
> otherwise damage them.

An keep the riff-raff (me) at bay and not bother the
developers with trivial matters.  You have to argue
with him to get things past him.
0
perl6
12/10/2019 3:55:38 AM
On 2019-12-09 07:00, Elizabeth Mattijsen wrote:
>> For some odd reason, some folks thought I was calling
>> him an actual dog (canine).  Would you have been
>> similarly offended if I had called him a "gatekeeper"?

> If you call someone a dog

I did not.  It is a figure of speech.  Please stop
twisting my words.

figure of speech:
https://www.wordnik.com/words/figure%20of%20speech

     noun: An expression that uses language in a nonliteral
     way, such as a metaphor or synecdoche, or in a
     structured or unusual way, such as anaphora or
     chiasmus, or that employs sounds, such as alliteration
     or assonance, to achieve a rhetorical effect.

     noun: idiomatic A word or phrase that departs from
     straightforward, literal language.

     noun: language used in a figurative or nonliteral sense


For those of your that do not love dogs, as we Yanks do,
when JJ said if he was a dog, he'd be a "Peanutbutter Lab",
he just describes himself as a sweet and loving spirit,
not a  actual dog.  That is why I teased him back about
being a Junkyard dog (look it up).  Again, neither one
of us were callign anyone an actual dog.  Both of
us were using Figures of Speech.


And now that you know I was not insulting him (believe
me, if I tented to, you would know it), would you please
desist in accusing me of doing such?

>> Is English your first language?

> No, is it yours?

Yes, and I should remember that when writing to this
group.  Not everyone understands Yanks figures of speech.
And not everyone first language is American English.

Thank you for your forbearance (I did not just call you a bear).

-T
0
perl6
12/10/2019 4:04:29 AM
--000000000000f2629805995b339c
Content-Type: text/plain; charset="UTF-8"

On Mon, Dec 9, 2019 at 12:49 Peter Scott <peter@psdt.com> wrote:
....

Developers need reminders, in the most succinct form, to minimize time,
> of data that they should not need to memorize.  The documentation
> satisfies that need in the same way that a phone book satisfies the need
> to look up someone's number.  The phone book is not bloated with
> explanations of each person's favorite food or the history of the phone
> company.
>
> Your 'keeper' documents sound like they should be shared with others who
> may be in the same situation as you.  Please follow the suggestions for
> how to do that so you can see how they are received.


I have a suggestion that might be a solution, and I tried to get interest
in it in 2015 or 16 when the docs were starting to get a lot of attention:

+ Start something like a Cookbook similar to the printed one published by
O'Reilly for Perl (but watch out for copyright issues such as identical
sections and layout)

Put the cookbook on the current docs site. The docs could stay the way they
are, but, as suggested above, have links into the cookbook for recipes for
real use cases like Todd wants.

With the tooling in place, Todd could start adding his stuff in the
appropriate place, and it would be fair game for editing as necessary.

Also as suggested above, the layout and links to and from the (reference)
docs and the example docs could be automated.

-Tom

--000000000000f2629805995b339c
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div>On Mon, Dec 9, 2019 at 12:49 Peter Scott &lt;<a href=3D"mailto:peter@p=
sdt.com">peter@psdt.com</a>&gt; wrote:<br></div><div dir=3D"auto">...</div>=
<div dir=3D"auto"><br></div><div><div class=3D"gmail_quote"><blockquote cla=
ss=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;pa=
dding-left:1ex">Developers need reminders, in the most succinct form, to mi=
nimize time, <br>
of data that they should not need to memorize.=C2=A0 The documentation <br>
satisfies that need in the same way that a phone book satisfies the need <b=
r>
to look up someone&#39;s number.=C2=A0 The phone book is not bloated with <=
br>
explanations of each person&#39;s favorite food or the history of the phone=
 <br>
company.<br>
<br>
Your &#39;keeper&#39; documents sound like they should be shared with other=
s who <br>
may be in the same situation as you.=C2=A0 Please follow the suggestions fo=
r <br>
how to do that so you can see how they are received.</blockquote><div dir=
=3D"auto"><br></div><div dir=3D"auto">I have a suggestion that might be a s=
olution, and I tried to get interest in it in 2015 or 16 when the docs were=
 starting to get a lot of attention:</div><div dir=3D"auto"><br></div><div =
dir=3D"auto">+ Start something like a Cookbook similar to the printed one p=
ublished by O&#39;Reilly for Perl (but watch out for copyright issues such =
as identical sections and layout)</div><div dir=3D"auto"><br></div><div dir=
=3D"auto">Put the cookbook on the current docs site. The docs could stay th=
e way they are, but, as suggested above, have links into the cookbook for r=
ecipes for real use cases like Todd wants.</div><div dir=3D"auto"><br></div=
><div dir=3D"auto">With the tooling in place, Todd could start adding his s=
tuff in the appropriate place, and it would be fair game for editing as nec=
essary.</div><div dir=3D"auto"><br></div><div dir=3D"auto">Also as suggeste=
d above, the layout and links to and from the (reference) docs and the exam=
ple docs could be automated.</div><div dir=3D"auto"><br></div><div dir=3D"a=
uto">-Tom</div><div dir=3D"auto"><br></div></div></div>

--000000000000f2629805995b339c--
0
tom
12/10/2019 3:31:04 PM
On 2019-12-10 07:31, Tom Browder wrote:
> On Mon, Dec 9, 2019 at 12:49 Peter Scott <peter@psdt.com=20
> <mailto:peter@psdt.com>> wrote:
> ...
>=20
>     Developers need reminders, in the most succinct form, to minimize t=
ime,
>     of data that they should not need to memorize.=C2=A0 The documentat=
ion
>     satisfies that need in the same way that a phone book satisfies the=

>     need
>     to look up someone's number.=C2=A0 The phone book is not bloated wi=
th
>     explanations of each person's favorite food or the history of the p=
hone
>     company.
>=20
>     Your 'keeper' documents sound like they should be shared with other=
s
>     who
>     may be in the same situation as you.=C2=A0 Please follow the sugges=
tions for
>     how to do that so you can see how they are received.
>=20
>=20
> I have a suggestion that might be a solution, and I tried to get=20
> interest in it in 2015 or 16 when the docs were starting to get a lot o=
f=20
> attention:
>=20
> + Start something like a Cookbook similar to the printed one published =

> by O'Reilly for Perl (but watch out for copyright issues such as=20
> identical sections and layout)
>=20
> Put the cookbook on the current docs site. The docs could stay the way =

> they are, but, as suggested above, have links into the cookbook for=20
> recipes for real use cases like Todd wants.
>=20
> With the tooling in place, Todd could start adding his stuff in the=20
> appropriate place, and it would be fair game for editing as necessary.
>=20
> Also as suggested above, the layout and links to and from the=20
> (reference) docs and the example docs could be automated.
>=20
> -Tom
>=20

I like the idea.  I also like it being centralized.

And Todd or whoever chose to write in it would get a lot
of great peer reviewing that would vastly help his/their
technical writing and programming skills.  And help
others too.
0
perl6
12/11/2019 1:14:22 AM
Reply: