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

Re: A grand idea on the documentation

Thread Previous | Thread Next
ToddAndMargo via perl6-users
December 10, 2019 03:46
Re: A grand idea on the documentation
Message ID:
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?  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:

Hi Peter,

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

>> 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.

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.

> 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.

The reason shy I asked her about English being her native language was 
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

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.

> 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.

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.

> 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.

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

>> 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.

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

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.

> 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

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 
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).


Computers are like air conditioners.
They malfunction when you open windows

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