develooper Front page | perl.perl6.users | Postings from December 2019

A grand idea on the documentation

Thread Next
ToddAndMargo via perl6-users
December 9, 2019 02:05
A grand idea on the documentation
Message ID:
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.


Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About