News for hackers. Stuff that matters.
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.