Re:The Most Important Language Feature No One Talks About
by aaronblohowiak on Monday October 19, 2009 @04:55AM
(#889753)
Good documentation includes examples. That's why `man` pages have an EXAMPLES section. The point you seem to be making about documentation organization being driven practically instead of horn-tooting, I completely agree with.
[ Parent
| on HN ]
Re:The Most Important Language Feature No One Talks About
by pavlov on Monday October 19, 2009 @05:08AM
(#889761)
Sorry if my point was so unclear. I agree completely that examples are an integral part of documentation. But it sometimes seems that this point is lost on the programmers and tech writers who should be collaborating to produce the documentation (or perhaps management is to blame for treating these roles too separately).
The result is often documentation that's too verbose, too rigidly structured according to the implementation's hierarchies and doesn't match the thought processes and expectations of the target users.
Re:The Most Important Language Feature No One Talks About
by aaronblohowiak on Monday October 19, 2009 @05:24AM
(#889770)
Right, and I was similarly unclear. I think that examples should be interwoven with the documentation, and I think that your insights into the systematic reasons for this are spot-on.
Re:The Most Important Language Feature No One Talks About
by stonemetal on Monday October 19, 2009 @08:44AM
(#889950)
>>Good documentation includes examples.
Should be: Good documentation includes good examples. Most example code out there is the worst code I have ever seen. Typically it looks like something someone slapped together in 5 min. Removing error handling to "improve clarity" just means that there are no examples of what errors the author of the library actually thinks are important or how to recover from recoverable errors.