On 11/12/25 2:52 AM, Richard Hainsworth wrote:
On Sun, 9 Nov 2025, 04:27 ToddAndMargo via perl6-users, <perl6-
[email protected] <mailto:[email protected]>> wrote:
On 11/8/25 11:59 AM, Richard Hainsworth wrote:
> Hi Todd,
>
> Long time since I responded to one of your questions.
Snip
Hi Richard,
I under stand why it is done that way. I just
do not like how it is done.
We all have our likes and dislikes.
I know you document things with your keepers. But to be honest the ones
you have published contain errors because they gloss over important topics.
For example in your next sentence:
"run" return its results in the OOP class "Proc".
There is an error! 'run' does NOT return it's results in the OOP class
Proc!!!
'run' returns an object of type Proc. This is important because you can
have many objects but there is still only one class. And the difference
between type and class arises because (in Raku but not in many other
languages) you can add roles to an object which means it will do more
than just the methods of class Proc.
And that is precisely what methods are documented by class and not by
the routines which return objects of that class.
The whole point of the secondary files is to aid in finding relevant
information.
But that is also the reason for the functionality in the search button.
I think everyone agrees that search and the website could be improved.
If you could find a way to suggest a systematic way of showing you how
to get the information you need in a more intuitive way, please let me know.
I'm writing a new version of the docs website. Take a look at https://
new-raku.finanayst.org <https://new-raku.finanayst.org>
It looks a bit like the old one, but it works better on mobiles and tablets.
There are bugs in it still.
Currently I'm working on an upgrade to the RakuDoc Renderer, so the bugs
will be there for a bit.
However I really would like to have a better search function.
I wish the documentation would define what is
put into your Proc variable when "run" exits.
Not divide it up all over the place.
Snip
And, I should not have to find the source code
more readable and explanatory than the documents.
And that should tell you something!
Thank you for the well written letter.
I appreciate it.
-T
Hi Richard,
After a lot of though, I think the best way to put this
so something is usable for both novices and experts
is to start as simple as you can get and then work up
to the advanced stuff. Perl5's perdocs are an
excellent example.
For instance, the "run" command. What is the novice
user looking for?
First a one sentence discretion about what it is doing.
Second, what do I feed it? Keep it really simple.
Don't do into any of the fancy features such as
colon pairs. Save all that stuff for later.
Third, what does it give me back. Just the basics.
What is most important in order of sequence is
First, exitcode. The program called's feedback is
useless if the call failed. Resist the urge to
explain about how it value got populated.
Second, the STDSTR.
Third, the STDERR.
Then stop there and send them directly to a
discussion of Proc. And start simple again.
No showing off until AFTER all the basics have
been discussed.
And that should be the end "run". If you start
giving examples, they won't know to go to Proc.
About your explanation of methods and other stuff
in your letters to me. They are wonderful. And I can
see why it is important to you. Raku's implementation
of OOPS is absolutely elegant. I can see where you
would want to shout from the roof tops about it.
The developers not only knocked it out of the ball park,
they knocked it out of the state into another ball park's
stands!
But you need to resist where you are going to find
novices. Someone just wanting to know how to operate
"run" does not need or want to know it came from a
method that eventually down the food chain made a
system call to the kernel. You just confuse them.
That being said, have you though of incorporating the
OOP (class) stuff you wrote me into a training document/
instruction manual?
You have a wonderful technical writing talent and Raku's
OOPs need to be shouted from the roof tops. It is beyond
imagination useful! Make sure you start by explaining
what OOP is, then advancing to Raku's class in an
implementation of it.
If you need any dumbed down examples to start with, you
know where to find me!
-T
