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 9, 2019 14:06
Re: A grand idea on the documentation
Message ID:
On 2019-12-09 02:48, JJ Merelo wrote:
> And I'm not really going to answer to the rest. It's simply not true. 
> You don't understand lots of things that are there, fair enough. You 
> don't need to. I always tell my students: "keep trying, and ask around 
> when you're lost". They never, however, convert their inability in 
> understanding something in a judgment on the quality of the material 
> used for learning, which has probably been evolved through generations 
> of other fellow students, so it's as good as it needs to be.

> You don't want to learn through the documentation, again, fair enough. 
> Use StackOverflow, books, whatever. Your call. I get the documentation 
> needs improvement. There are ~300 issues that need to be solved. We do 
> what we can. But let's not throw the baby with the bathwater. Let's keep 
> improving the official documentation, and let's try to make it as good 
> as possible for the majority of developers out there.

What school did you go to?  Students rate good and bad
teachers, good and bad material ALL-THE-TIME.

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.

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.

Did you see my post of ".contains".  I took the cryptography
apart and explained what the heck each part of it meant.

Do you think any of that actually helped me use ".contains"?

Do you think I even remembered what it meant?

When I have an issue, I first go to the docs.  I have
to shake my head over how unnecessarily difficult they
have made things to understand.   If I can't pick it out
from any of their examples, then it is off to Google.

Perl 5 is not this way.  Raku should not be either.  And
the reason I keep beating a dead horse.

I am not trying to throw the baby out with the bath water.
I am trying to get more folks involved.

As long as the Doc's culture is "the answer is intuitive
obvious and let to the student to figure out", the docs
are going to remain difficult to use by standard programmers.

Before the docs can become useful, the intended audiance must
be changed.


I don't think you are a canine.

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