On 27-Jul-99 Thomas J. Hamman wrote:
> Snipping the rest since I don't even disagree with it. :) I do agree with
you
> about the current situation of documentation for Linux--especially where
the
> HOWTO's are concerned, since many of them seem to be very outdated.
(Though I
> find it hard to find too much fault with the people who write them, who
gain no
> money for the time they spend on it.)
I realize they are uncompensated, but on the other hand, they signed up
knowing the terms up front. I've done volunteer work before, and the pay is
always the same: the satisfaction of having done something beneficial for a
group. If they tire of it, or if they find themselves unable to carry on for
any reason, they have a responsibility to hand off to someone who can
continue the work. As Linux is a living thing, so must the documentation
live and grow.
> I wasn't aware that Mandrake had a separate 'user guide' in addition to
its
> installation guide. If so, I would agree that that (the user guide) is a
proper
> place for information about SCSI emulation.
They call it a user guide, but I put it in quotes partly because I disagree
with its designation. It isn't close to being a user guide. And more
importantly, what is needed is not a guide, but a manual.
If I harp on this, understand that I am frustrated at the shortfalls. I'm
convinced that Linux could be better for my company than Windows, but am
concerned at the risks implied by poor documentation.
To be fair, I think this is an hereditary issue endemic to C programmers. C
docs have always been sparse, as have Unix docs. The mindset has favored
small programs, and also favors the creation of tiny programs to allow each
programmer to discover personally how a function works. For reasons I have
never understood, the entire C community seems to find that appropriate. It
put me off 15 years ago, and it still does.
My outlook may also be colored by my having started in hardware design. And
when I moved from logic to programming, it was in assembler first, where
copious docs of registers and bits and address spaces are always available.
Revisiting my complaint with the serial programming HOWTO, that is exactly
the approach which is needed there, with each control bit fully explained as
to function.
I've also been spoiled through years of working with Pascal, where a single
company dominates the field, and where there documentation has always been
pretty strong.
Part of my frustration comes from the fact that if I had the time to spend
on doping out the serial programming details, I would offer an update to the
HOWTO. Unfortunately, I don't have the time to do that. In fact, that issue
alone is forcing me to reconsider the move to Linux -- forcing me to buy
into Windows for another product generation. Frankly, that is so depressing
that I've been thinking maybe I should go back to hardware design. Or switch
to BeOS. Or look again ad DOS with DR-DOS, and go back to assembler. I
really have come to hate Windows.
William Meyer
