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

Re: A grand idea on the documentation

Thread Previous | Thread Next
From:
Peter Scott
Date:
December 9, 2019 18:48
Subject:
Re: A grand idea on the documentation
Message ID:
256e6125-81a8-6114-4604-fda91e073fd0@PSDT.com
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:

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

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.

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.

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.

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

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

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About