Quoting Steve Litt ([email protected]): > Rick Moen <[email protected]> wrote: > > > http://linuxmafia.com/~rick/lexicon.html#moenslaw-documentation > > > > Moen's Law of Documentation > > > > "The more you write, the less they read." > > Not true, if you structure the writing correctly. Especially now that > we have hyperlinks, it's easy to write good and non-ambiguous docs.
Well, I've seen the effect I describe at said lexicon item play out in the real world, over and over, with writings from untold numbers of technical people. However, I admire your optimism. Absolutely, I do endorse your notion that part of the problem is reliance on excessively linear prose. As I said, IMO that's a big part of the structural problem with Eric's and my essay. > Yes, but in a "how to do it" document (like documentation on a distro's > install procedure), once you've articulated the steps and substeps and > what could go wrong and how to deal with it, you're done. I _really_ admire your optimism. ;-> > All things being equal, concise is always better than rambling. But man > pages are concise.... Even the one for GNU find? ;-> _______________________________________________ Dng mailing list [email protected] https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
