On Fri, 2006-06-09 at 11:09 -0500, Steve wrote:
William L. Maltby wrote:
So what's GNUsworthy about that? Same old problem new millenium. Unlike
<snip>
I guess we're getting off topic, as this is hardly a CentOS only problem.
True and I hope all know that no one was speaking of CentOS, certainly, or any particular ...
But... documentation is a perfect example of where commercial entities can really help. Companies like RedHat can and do pay people to go through the drudgery of writing docs. And, to be fair, things are *much* better than they used to be. Today, you can pretty much count on being able to "man zwonkumd.conf" and get some documentation on that config file. Back in the RH 6.x days, I remember that was a rarity.
Yep to all. However, after initial doc generation, keeping it maintained as the system changes is an even harder task than the gen of initial versions. So one must ask "What is the worth of documentation that can not be relied upon to be accurate and current and complete *most* of the time"?
Then all the ball-buster "gurus" who say "read the code if you want to know what's really happening ..." kick in their $.02.
It wouldn't hurt, though, if more projects would take the "Until it's documented, we won't advertise it as a feature" attitude. I believe that Debian has such a policy about their distro.
That's an outfit that we can support.
Thing is, though, we CentOS users have little right to complain.
?? "If you can't complain, you're not trying hard enough!". ;-) We can complain in light of the overall environment, but *not* about CentOS in particular, IMO. Gen of non-<your-fav-distro>-specific docs is certainly outside the <your-fav-distro> project scope and anyone complaining to/about <your-fav-distro> is off base.
The project that creates/maintains the software/component is responsible for the failure. Undocumented project-specific changes are the only failure of a specific project.
Paying RH customers do. But we can hardly fault Johnny and gang. We have no recourse but to ask "Why hasn't someone documented XYZ?". To which the answer is the perenial "Because no one has cared enough to do it. Hey why don't *you* do it after you get it all figured out?". Which is always pretty irritating, because it is so true.
However, we do have the absolute defense: "Because I don't want to any more than you. Regardless of the fact that you generated the super-whiz- bang software, it places no obligation on me to do the drudge work you chose to ignore, nor does it reduce my right of free speech nor increase my debt of gratitude. You chose to develop it; I have no obligation to appreciate it at all. If I do so, *you* owe me, It's your ego that got satisfied. If there is less satisfaction because now I can't use it due to poor/no documentation, tough for you". :-)
-Steve
<snip sig stuff>
I speak as a former *long-term* developer who hated doing docs but did them anyway as a point of pride, concern for my users and egocentric individual who wanted to be able to say "No one would do it better". :-)
It only took a couple "lazy" times to come to that attitude.