[Tutor] The Reading Documentation problem

[Mike Barnett]

I had hoped not to sound too rant-like, but alas guess it does come off sounding like that.  It's frustration that maybe leaked through.

I honestly don't think, in this particular case, that it's a documentation quality, lack of, or outdated.  I've heard from numerous users that it was the documentation that drew them in and kept them using it. 

I come from an era where documentation was paramount and engineers were expected to write technical docs.  Technical writing and lack of clear examples is not my problem.  I don't say that to be arrogant or defensive, but rather  to say that I'm too much of a "continuous process improvement" person to let bad or non-existent documentation to be a problem.  

I come out and ask the people that clearly didn't read the docs what kinds of changes I could make that would have helped them.  Most of the time that answer is "nothing, I just didn't take the time to read them... I'll do that next time".

I'm speaking of a phenomenon and I think you've done a great job Dave of adding some color and detail to the conversation that is helpful.  

There IS a "I want it now" culture.  I see the "how can I become employable in 1 year" questions on Reddit every other day.

The reason I wrote to this list is that I assumed it was monitored by teachers, tutors, those that are further upstream than me.  It's a request for help I suppose I'm asking for.  But, now that I think about it, the people I struggle with getting to read the docs are not in touch with these educators.

I sometimes send private messages to folks asking for super-quick learning, giving them my opinion of a path they could take or stressing this or that part of what they are doing that they are perhaps lacking a little.  The responses are often surprising.  They're overwhelmed with gratitude, saying that no one has taken the time in their past to teach them this or that part of being an employee or learning.

Thanks for the frank conversation on this without it turning into finger pointing.



-----Original Message-----
From: Tutor <tutor-bounces+mike=pysimplegui.org at python.org> On Behalf Of David L Neil
Sent: Sunday, August 25, 2019 4:32 AM
To: tutor at python.org
Subject: Re: [Tutor] The Reading Documentation problem

On 25/08/19 11:04 AM, Mike Barnett wrote:
> I've noted what I find to be a disturbing trend with younger students that use a package that I released last year.  This package has a LOT of documentation, and it's needed because there are a lot of different classes, functions, etc.  It's really easy reading and you don't have to read the docs except when you run into trouble or something new about it that you're learning.  It's not a difficult package to learn and use, even with little reading.
...

> Sorry this is so long, but it's a real problem I'm witnessing and I'm wondering if it's only a certain portion of the programming world (self-taught people) or the internet-generation in general does this regardless of educational training.


One good rant deserves another:-


Today's pace of life - I want it now!

The general rule is that documentation is weak, out-of-date, or non-existent. The rationale for which seems to be: read the source-code.

So, many people are self-taught and appear to do so without following any form of structure or syllabus.

Training courses are expensive and thus necessarily short.

Many believe that 'boot-camps' are a more efficient way to learn than
3?4 year university programmes.

The average length-of-career in IT is quite short. Assuming that course-applicants have realised this, surely the training lead-up should reflect same?

Employers want someone now, not in three-years' time/I need a new
(highly-paid) job now, not in three-years' time.

How many people can distinguish between a "coder" and a "programmer" - particularly employers/clients/HR depts.

Why spend time learning when StackOverflow is but a click away?

Why spend time thinking when someone else has already coded it/something (which appears to be) similar?

Governments (world-wide) are tending towards the employers' preference for "training", as distinct from the life-long preparation of "education". This also a feature of "the gig economy", and the expectation that one can inter-change individuals, as long as the job gets done.

Similarly, I see (again, widely-spread across the 'western world') a lack of respect for academia ("all brains but no practical use"), and thus the claim that renamed polytechnics/technical colleges/community colleges produce 'just as good' a graduate.

Cash now/soon, or no cash until later - who is good at "delayed gratification"?

It's called a ?brave, new world...
--
Regards =dn
_______________________________________________
Tutor maillist  -  Tutor at python.org
To unsubscribe or change subscription options:
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmail.python.org%2Fmailman%2Flistinfo%2Ftutor&data=02%7C01%7C%7C0b63e8b0e4bb4c337bf608d72936be73%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637023187402679526&sdata=M3AnFoKoQzIby0aMLi7a9BCGpecjUW9CjUXHnxBfrBU%3D&reserved=0