Read other letters about this article

• Saturday, November 25, 2006 04:29 AM

  Just write better instructions for beginners

  The first thing that's needed is qualified technical writers who know how to write for the age of their audience. Then some of today's popular languages wouldn't be so bad.

  As of now, Perl documentation is a mess. Much of it was written by various people of unknown qualifications.

  I think Python's documentation was written by Python's developer who, as far as I know, isn't a qualified technical writer and his work wasn't professionally edited.

  I remember not even being able to find online Javascript documentation a couple of years ago that didn't have glaring omissions or wasn't self-admittedly out of date. I challenge anyone to find any Javascript documentation, tutorial, etc. on the internet that mentions that setTimeout starts a new thread, much less something that explains what that is and how to work around it to implement a time delay. I was eventually pointed to something that mentions the threading, but it wasn't documentation or a tutorial and therefore wasn't in the proper place. The fact that there's no "sleep" is another issue. The reasoning for having no sleep is bogus.

  The technical writers of beginner's material should be instructed to mention "best practices" such as avoiding goto, declaring variables, turning on warnings, etc., only at the end of the book. With simple programs, memorizing and using that stuff just makes things harder.

  Line numbers are good because they make it easier use goto. No need for a beginner to learn label syntax or what can and can't be labeled. That's one thing that documentation can't provide.

  There's a similar discussion at http://www.aota.net/forums/showthread.php?t=22202

  Python is easier and better than Perl. See http://www.polisource.com/PublicMisc/Benchmarks_Perl.html

  —Barry
  Permalink
  Flag
  Click "Submit Flag" if you feel this post is inappropriate. Explain why below if you wish.

  Cancel