Jeremy, I liked your post and I agree with you about the need for great documentation. I think a lot of documentation is geared toward people who are already in the know. Even with a well-documented language like Perl (which is my first programming lanuage), most of the battle was learning the jargon. At first, looking at a perldoc was like reading ancient Klingon. Programmers tend to write for the programming audience. Thankfully, there are some great books and documents that helped me out tremendously. It still took a lot of work but I can at least read most of perldoc now and understand it.

I often wonder why programmers fail to dumb down their documentation. I would hazard it's easier for them to write at a more abstract level. It takes a tremendous amount of work to put yourself in the place of a newer programmer and write about the world from his/her perspective. Also, perhaps because they have been trained to think in compact ways, programmer authors are frequently too concise. Just about every sentence they write is packed with information with very little "storytelling" behind it. Instead of spreading an important idea over 3 or 4 pages like a novelist might, programmers tend to pack that kind of idea into 2 or 3 sentences.

Though inaccurate in quite a few places, I think Learn (Baby) Perl in 21 Days was one of the best programming books I ever read. The writing style/approach to teaching Perl was just the book for someone like me who was unfamiliar with all but the most basic programming techniques. The author takes a narrative approach and was careful to cutback on the jargon and gently introduced new jargon when necessary.

Anyway, keep writing the thorough documentation. To be more concise about all this: I think it's much better to be too wordy then too brief. Sure the veterans won't find it as enjoyable to read, but many newer programmers will be deeply appreciative. Please keep them in mind when your write.

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop";
$nysus = $PM . $MCF;
Click here if you love Perl Monks