3 ms·
Good documentation includes examples. That's why `man` pages have an EXAMPLES section. The point you seem to be making about documentation organization being d
by aaronblohowiak 17y ago
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.
- pavlov 17y agoSorry 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.
- aaronblohowiak 17y agoRight, 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.
- stonemetal 17y ago>>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.