On 12/28/20 4:54 AM, Richard Hainsworth wrote:
Todd,
Some of what you have said in this email list over the years has been
very valuable. You ask questions that get some very illuminating
answers. I wrote a Module just for you (although I' still trying to get
it to work on Windows) and it inspired me to look much more deeply at
GTK::Simple, which I have just become the maintainer for.
So please take what I say now as a plea for you to adapt a little, not
to get pissed off with us even though you do seem to have pissed some of
us off.
You have very definite ideas about what the documentation should and
shouldn't be. You have stated them over and over again. The Raku
community at large - based on replies from multiple individuals over the
years - disagrees with you.
The Raku community has come to the concensus that there is a distinction
between Tutorials and Reference, and that the Documentation site should
contain both. Tutorials define how to use some aspect of Raku, with
example text and explanation. Reference tries to cover as much of the
language as possible, covering all the methods/subs/names/types etc as
possible. Reference is written for a person who already knows how to
program and who uses Raku. The assumption is that if a person reading a
reference does not understand some term, then s/he will search in the
documentation on that term to understand it.
No set of documentation standards will please everyone - that's life.
Even so, there ARE STILL areas of the Raku documentation that are
lacking (just look at the issues on the Documentation repository, any of
them raised by our indefatigable JJ).
However, the balances between prolixity and brevity, examples and
assumption of knowledge, exhibited in the Raku Documentation do by and
large reflect a community consensus.
It is polite in a community of rational human beings to accept what
seems to be the general consensus, even if you do not agree with it. By
continuing to demand your views about documentation should be accepted
without any support from anyone else, is quite irritating. So please try
to find a different way to express ways to improve the documentation
that will not piss people off.
You have suggested in this email list a variety of 'keepers', which seem
to be the way you document your use of Raku. However, these 'keeper'
texts are full of spelling mistakes, indicating you do not use a
spell-checker, and also are ambiguous or technically wrong. Personally,
I have not found your keepers to have been any use at all. But they may
be useful to someone. Even worse, it is not possible for me to find a
collection of your keepers because they are in posts to this email list,
and I am not going to search through thousands of emails for your
keepers on something whose keywords I would need to guess at. So the
form you have made the keepers available is not easily accessible.
In addition, the way the Raku community has evolved to work is to make
changes to Documentation, whether Tutorials or Reference, by actually
suggesting changes. If you look on the upper right of any primary
document (the docs.raku.org site displays pages that are both
automatically generated from primary documents, and the primary
documents themselves - basically the documents referenced from the home
page), you will see a Pencil icon. Click on that, and you will be taken
to the github site and you can directly edit the document. The change is
then submitted as a Pull Request, and it will be reviewed. If the change
is seen to be reasonable, it is included.
In this way, every single member of the Raku Community has the ability
to make or suggest a contribution.
However, a word of caution about human nature. If you go and try to
completely change all the documentation to the way you want it, trashing
everything that has already been contributed, it is extremely unlikely
that your amendments will ever be accepted. Further, you run the risk
that contributions with your name will never be considered by the Core
Developers because they have rejected PRs you made before.
Contribute in a way that enhances the Documentation, and your work will
be praised.
I hope whatever end of year, mid-winter or religious festival you
celebrated was festive, even in our pandemic afflicted world, and I wish
you a safe and productive CE 2021.
Regards,
Richard
Hi Richard,
Thank you for the insightful letter. Please know that I do deeply
appreciate the help people give me here and think the
world of everyone who helps me. I have zero intention of
pissing anyone off. That would be a very foolish move
on my part.
I do not believe the documentation should be completely
changed, but instead added to make things more
understandable. I do believe the framework is generally
good. I believe the documentation should be build on and
not trashed and redone. I do apologize for any
misconception/misunderstanding I may have created on
this issue.
I think that with a small amount of effort, they can be
made to be more understandable. Right now they are mostly
only refreshers for those that already know what they are doing, like
yourself. With a little extra detail added,
they can be both a refresher and a teaching tool. There
is no reason why they can't be both.
For instance, a nice start would be to no expect everyone
to know what the defaults are and fill them in on
the definitions lines, when introducing a concept, like "class" make it
a link to a written explanation of
the concept, and to move examples with complex functions
(no showing off) to the end after first showing a
simple example. Your pencil tip will be helpful.
It would also be helpful if the word "tutorial" was
removed when they are not meant as tutorials, as in
the class tutorial.
My "Keepers" are not meant for use by experienced users
like yourself. But I do appreciate when experienced users
criticize my mistakes as it helps me improve. If I ever
manage to teach someone of your talent something from one
of my Keepers, I will be astonished, if not somewhat
flattered. (I have a Keeper in the works for OO, but it
needs some work on the Native Call examples.)
And, I am not seeking fame or credit when I post a keeper.
I am trying to pay back for all the extraordinary assistance
others have given me. Not everyone on the mailing list
has your experience. Please do not misunderstand.
Now the misspelling, this is my Publik Skool background.
If I did not have a driver's license, I would not remember
how to spell my own name. It did not stop me from graduating
with honors from university, but it was a thorough pain in
the butt. And as Mark Twain stated
"Anyone who can only think of one way to spell a word
obviously lacks imagination.”
I write my keepers in a text editor because it lends more easily to copy
and paste from terminals to test things
and it is much easier to paste to a newsgroup as a lot
of readers do not scroll well as does a word processor. It
would look prettier on my end if I switched to odt, but
would be miserable at your end switching it to text.
There is no web site for my stuff in my future as I simple
do not have time to maintain it.
On the GTK::Simple front, I really appreciate your work on
the project. This one of the missing features in Raku.
I would love it if you could also use your experience with
GTK::Simple to add examples of interfacing with Glade.
Here is wishing you and all of you a very happy and prosperous New Year!
-T
