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
In reply to Re: use documentation;
by nysus
in thread use documentation;
by jepri
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |