[Tutor] The Reading Documentation problem

[mhysnm1964 at gmail.com]

Mike,

It is a combination of poor documentation where the author does not provide clear examples  or explanation all the way to where someone is learning and do not understand some of the terminology. Sometimes the developer is not the best person to right the information on the module. This is why we have technical writers. 😊

But your right. I don't know how many so call developers I have spoken to over the years of doing my work who do not understand some core concepts in the web space. You ask them why did you do it this way, and they have copied it from somewhere as it addressed their needs without understanding the code fully.

I don't know if it will get any better due to some of the tools available making it easier to write code without knowledge. Reading technical information is important.



-----Original Message-----
From: Tutor <tutor-bounces+mhysnm1964=gmail.com at python.org> On Behalf Of Mike Barnett
Sent: Sunday, 25 August 2019 9:04 AM
To: tutor at python.org
Subject: [Tutor] The Reading Documentation problem

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.



There are a lot of materials supplied along with the User Manual... a Cookbook, a lot of demo programs.



The trend I see is an unwillingness to do a search through the documentation when there's a problem and instead of "researching" their problem some of these youngsters post, or blast post across multiple sites, a request for help.  Often  the information could have been found by searching online documentation much quicker and with a LOT less work than typing up a Stack Overflow post.



Reading the documentation is an essential skill to grow knowledge.  I get googling for help.  I do it from time to time too.  But when there's documentation available, you can't go wrong generally speaking by looking at it.  When I learned Computer Science I had no choice.  There was no internet.  I remember when 2 foot long groups of manuals were placed on tables for easy access in computer labs in universities I attended.   I feel like it made me a better programmer.



I would like to request that teachers really drill in the importance of reading documentation, and while on the topic, writing documentation is super-important too.  I understand the super-fast-pace of learning and doing that we're going through in technology, and the desire for instant learning or instant answers. I get that there are some great resources on the net.  But they shouldn't be used in place of the written word, published often by the developers of the code.



The problem with getting info online from Reddit, Stack Overflow, forums, is that sometimes, or for my not yet well-known package, all the time, the information is wrong.  Reddit in particular is scary as I watch person after person respond to questions when they don't know much or anything about the topic.  It's as if answering first gets them something.  I dunno if it's an ego thing or what.



I just know what I see and what I see time and time again are people without actual education and knowledge answering questions with the authority & confidence of someone that does know the topic.  It's nearly impossible sometimes to tell the difference between someone completely guessing and someone highly educated just by reading the text posted.



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.



Thank you for your time



_______________________________________________
Tutor maillist  -  Tutor at python.org
To unsubscribe or change subscription options:
https://mail.python.org/mailman/listinfo/tutor