Front page | perl.perl6.users |
Postings from December 2019
Re: A grand idea on the documentation
From: JJ Merelo
December 9, 2019 10:48
Re: A grand idea on the documentation
Message ID: CAJoLtgdUmhjJ+A9eN1VSjsg3sTZT489F9rET5Zx0DxZ9h8gT4g@mail.gmail.com
El lun., 9 dic. 2019 a las 11:26, ToddAndMargo via perl6-users (<
> On 2019-12-09 01:52, JJ Merelo wrote:
> > El lun., 9 dic. 2019 a las 10:34, ToddAndMargo via perl6-users
> > (<email@example.com <mailto:firstname.lastname@example.org>>) escribió:
> > 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
> > > write your own and help yourself and maybe others, there're lots
> > > 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 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
> > 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
> 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
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
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
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.