On Thursday 26 April 2007, Ed Greshko wrote: >Gene, > >> But I have to ask again, where in tuncket are the docs on this stuff? Why >> do Ric and I, and lots of others by inference, have to hit the end of our >> rope and blow up using 3 and 4 letter words before info such as this is >> made available? > >Dare I say this is "normal"? Speaking in generalities, developers don't >enjoy doing documentation. Also, generally speaking, developers make poor >documenters. We both know that Ed, and I dare say quite a few of the users have realized this over the last 5 years as the docs situation has slowly deteriorated. The writers think its just as easy to put the info on the net & walk away, hiding from any email asking questions while they work on the next great thing. But whats on the net is very often volatile and by the time we manage to find it, 2 generations obsolete. Back when I was carving code for the amiga, I made sure that if I didn't get around to doing decent docs, anyone walking through it could figure out how both my mind, and the program worked, just by reading the comments. Heck I even went to so far as to include within one printer driver I wrote, a key dot command that would cause the program to scan its own code and print the comments in manual form, probably resulting in a better explained utility than a manpage did 5 years back before everybody got on this xml crap and then didn't bother to tell any but the very geekiest, how to run a conversion proggy and actually get an info or manpage out of that crap that was actually readable. >I worked for a company that transitioned from a hardware company to more of >an integration and software company. The demographics of the company >remained largely the same. i.e. Mostly engineers and techies. The result, >good software, horrendous documentation. And, these folks were paid. I believe the release managers for most distro's are too. Except for debian maybe. I'd think that enforcing good docs out of this "herd of semi-feral cats" could be done a little more firmly. Sigh... >> There is something very very wrong with this picture. -- Cheers, Gene "There are four boxes to be used in defense of liberty: soap, ballot, jury, and ammo. Please use in that order." -Ed Howdershelt (Author) Be frank and explicit with your lawyer ... it is his business to confuse the issue afterwards.
