On 12/14/2012 06:58 PM, Bill Gradwohl wrote: > My point was to DESIGN for html and the rich environment it offers, not to > try to convert a Model T into a Mercedes. > > I'm not wild about a wiki either, if its a free for all. If on the other > hand, it is a submission platform that gets reviewed and edited by the > developers then it's possibly of benefit, especially for examples. > > The best technical document I ever encountered was the DOS C compiler from > Microsoft over 20 years ago. At about 1.5" thick, the book that came with > it was excellent. I kept the book long after I ditched the compiler. Every > item listed in the index had sample code associated with it that not only > showed how to use the item, but also provided examples for the boundary > conditions that reinforced what the documentation said. > AFAICS, there's nothing in Texinfo preventing a developer from writing such an excellent documentation; what prevents it is typically the fact that writing good documentation is hard, subtly complex, time consuming, and tiring. No silver bullet for that; a tool or a format can only remove the non-essential, "mundane" difficulties, not the intrinsic ones.
> Absolutely > excellent documentation. It used the K&R style but applied it to the entire > subroutine library. > Regards, Stefano
