I've been using Linux for 8 years now. It was a
huge learning curve for me but it was worth it.
I'm now using Slackware 9.0 with a 2.6.0 kernel. I
can see plenty of activity and lots of changes
taking place in the linux code. Alsa sound
drivers, module-init-tools are two good examples
of sweeping change. Change is good! Don't get me
wrong. I'm always impressed by the speed at which
these updates appear.

However, I have to say that the documentation for
Linux is stale and outdated. Most howtos at the
tldp.org are more than 3 years old and are hardly
relevent any longer. Alsa docs are pitiful and
module-init-tools docs are equally dim considering
how drastically that package changes the system
and how it boots.

This inability to keep docs current coupled with
the poorly crafted subject lines in newsgroups
threatens the future of Linux. For the average
end-user there is not enough inforamtion available
to utilize the newest inclusions.

I consider myself only slightly above average with
8 years of experience. But, when I read endless
docs with cirrcular references and spend months
trying to debug the same stupid issue that I fixed
under Windows in a matter of minutes I have to
wonder why I'm using it anymore. It's not like I'm
going to get a job in the field anytime soon.

Certainly Windows friendly hardware manufacturers
can shoulder most of the blame for this however,
when the ingenuity of the Linux community
overcomes this closed-source obstacle it hardly
does any good unless they can share that success
with ALL Linux users. For example, if I'm trying
to get alsa drivers to work with my SBLive (fairly
generic card) it doen't really help me a great
deal to read endless docs that discuss the topic
at the hardware bit level. I need docs designed
for the end-user because I have no desire or
intention of studying sound cards at the level
which they are discussed in these docs. I just
want my sound card to work properly.

When I began using Linux I was prepared for a
steep learning curve and I accepted the fact that
whatever I could do in Windows was going to take
my longer to accomplish under Linux. But after 8
years of using Linux this gap is widening. And
frankly the frustration is becoming intolerable
because there is no payoff, there is no solution
unless I want to study and learn everything that
the programmer knows. So, when I read docs that
assume that I know everything the author knew
prior to writing the doc I just shake my head and
say, "what an asshole"!

I don't want to mention a name here although this
guy really pissed me off by not detailing the
requirements for his program. Oh, he hinted at
what was required but I had to compile the f'n
thing 2 dozen times and then track down each error
and discover on my own which packages were
required. This a-hole wouldn't even respond to my
request for help. Here's a quote from his page,
"You also have to install the devel packages for
the various libraries used by PROGNAME(removed to
protect the obtuse individual) (glibc-devel,
libjpeg-devel, ...)" Nice list of requirements,
eh? "Various libraries," and "..."! What the hell
is the big secret? Jesus H! Would it kill this guy
to paste the requirements into the README or his
webpage or somewhere? There is NO excuse for that!

I just shake my head and say, "what an asshole"!

That's my $0.02

Paul Becker

In alt.os.linux Paul Becker <paulisnot@home.com> wrote:

[ Please set Followup-To ]

[ lots of stuff ]

> I don't want to mention a name here although this
> guy really pissed me off by not detailing the
> requirements for his program. Oh, he hinted at
> what was required but I had to compile the f'n
> thing 2 dozen times and then track down each error
> and discover on my own which packages were
> required. This a-hole wouldn't even respond to my
> request for help. Here's a quote from his page,
> "You also have to install the devel packages for
> the various libraries used by PROGNAME(removed to
> protect the obtuse individual) (glibc-devel,
> libjpeg-devel, ...)" Nice list of requirements,
> eh? "Various libraries," and "..."! What the hell
> is the big secret? Jesus H! Would it kill this guy
> to paste the requirements into the README or his
> webpage or somewhere? There is NO excuse for that!

> I just shake my head and say, "what an asshole"!

Mh, the time it took you to write this message, you could have
used to write the few lines for this progs README what kind of
stuff is required and send it to the author.

Guess he would have luckily added your lines to the README and
add your name to the *glory* of the CHANGES file.

--
Michael Heiming

Remove +SIGNS and www. if you expect an answer, sorry for
inconvenience, but I get tons of SPAM

Michael Heiming wrote:
> In alt.os.linux Paul Becker <paulisnot@home.com> wrote:
>
> [ Please set Followup-To ]
>
> [ lots of stuff ]
>
>
>>I don't want to mention a name here although this
>>guy really pissed me off by not detailing the
>>requirements for his program. Oh, he hinted at
>>what was required but I had to compile the f'n
>>thing 2 dozen times and then track down each error
>>and discover on my own which packages were
>>required. This a-hole wouldn't even respond to my
>>request for help. Here's a quote from his page,
>>"You also have to install the devel packages for
>>the various libraries used by PROGNAME(removed to
>>protect the obtuse individual) (glibc-devel,
>>libjpeg-devel, ...)" Nice list of requirements,
>>eh? "Various libraries," and "..."! What the hell
>>is the big secret? Jesus H! Would it kill this guy
>>to paste the requirements into the README or his
>>webpage or somewhere? There is NO excuse for that!
>
>
>>I just shake my head and say, "what an asshole"!
>
>
> Mh, the time it took you to write this message, you could have
> used to write the few lines for this progs README what kind of
> stuff is required and send it to the author.
>
Well, I'm hardly qualified to add anything to
anybodies README files. When my solutions are
guesses or pure dumb luck do YOU really want to be
reading docs prepared by ME? Sounds like an
invitation to be flamed.

> Guess he would have luckily added your lines to the README and
> add your name to the *glory* of the CHANGES file.
>

In alt.os.linux Paul Becker <paulisnot@home.com> wrote:


[ Can't post to alt.linux here, alt.os.linux works fine ]

> Michael Heiming wrote:
> > In alt.os.linux Paul Becker <paulisnot@home.com> wrote:

[ Some GPL prog misses the required libs/etc mentioned in README ]

> > Mh, the time it took you to write this message, you could have
> > used to write the few lines for this progs README what kind of
> > stuff is required and send it to the author.
> >
> Well, I'm hardly qualified to add anything to
> anybodies README files. When my solutions are
> guesses or pure dumb luck do YOU really want to be
> reading docs prepared by ME? Sounds like an
> invitation to be flamed.

Guess the author would have double-checked your submissions, that's
how it all works. Perhaps you haven't been "down" this deep in
the world of Linux, but there's nothing special about it.



--
Michael Heiming

Remove +SIGNS and www. if you expect an answer, sorry for
inconvenience, but I get tons of SPAM

On Sun, 01 Feb 2004 21:47:55 GMT
Paul Becker <paulisnot@home.com> wrote:
> However, I have to say that the documentation for
> Linux is stale and outdated. Most howtos at the
> tldp.org are more than 3 years old and are hardly
> relevent any longer. Alsa docs are pitiful and
> module-init-tools docs are equally dim considering
> how drastically that package changes the system
> and how it boots.
[snip]

So, it scratched an itch. A good moment to start writing .

With kind regards,
Daniel de Kok

> ---snip---
> This .> I don't want to mention a name here although this
> guy really pissed me off by not detailing the
> requirements for his program. Oh, he hinted at
> what was required but I had to compile the f'n
> thing 2 dozen times and then track down each error
> and discover on my own which packages were
> required. This a-hole wouldn't even respond to my
> request for help. Here's a quote from his page,
> "You also have to install the devel packages for
> the various libraries used by PROGNAME(removed to
> protect the obtuse individual) (glibc-devel,
> libjpeg-devel, ...)" Nice list of requirements,
> eh? "Various libraries," and "..."! What the hell
> is the big secret? Jesus H! Would it kill this guy
> to paste the requirements into the README or his
> webpage or somewhere? There is NO excuse for that!
>
> I just shake my head and say, "what an asshole"!
>
> That's my $0.02
>
> Paul Becker
>

I have to agree with you. The problem here, i think, is that many good
software developers often are very bad educationalists. It seems that these
two areas demand very different skills from a person.

It is also a problem with documentation that these are not clearly targeted
to a specific audience.
It would be nice e.g. if every project on sourceforge would label the
documentation with respect to the target audience. That is 'End User' and
'Developer'. But sometimes developers don't have the time to do a good job
here. And it's true that sometimes (thankfully seldom) there are really
assholes out there thinkin their proggies are the salvation to the human
race and need no further explanation or documentation.

bw

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: Eicq - The XEmacs ICQ Client <http://eicq.sf.net/>

iEYEABECAAYFAkAdl40ACgkQHSfbS6lLMANGUQCcCDOmskmDeE OgQWMM9FQr38sW
SFsAoL15J5c91BChPDzPyj8LS0dMOTAN
=dTyj
-----END PGP SIGNATURE-----

Steve Youngs <sryoungs@bigpond.net.au> wrote:
> * Paul Becker <paulisnot@home.com> writes:

> > However, I have to say that the documentation for Linux is
> > stale and outdated.

> A lot of it, yes, but on the other side of the coin, a lot of
> documentation is right up to date, _and_ a lot of the old stuff is
> _still_ relevant today.

Most linux documentation is junk, written by high-school kids and
college dropouts who seem to feel it is "kewl" to mispell at least
half a dozen words per page of documentation.

> > This inability to keep docs current coupled with the poorly
> > crafted subject lines in newsgroups threatens the future of
> > Linux.

> Being a newsgroup poster yourself, Paul, you are contributing to
> the situation. I'll leave it up to the reader to decide whether
> your contribution is positive or not.

You're merely a cheerleader and as such, you do far more harm to
the linux community than objective critics do. For you everything
linux is good and as long as there are morons like you running
around the faults of linux will not receive the attention they
need in order to be corrected. User-friendliness in both programs
and documentation are at the very top of the linux fault list. If
you don't know this, then lurk until you do. It may be that linux
cannot be made any easier to use than it is now. But pretending
that all is rosy when it's not is clearly less than helpful. Linux
is free and yet Microsoft's installed base grows everyday. Most
people look at linux and see something not worth paying for.
Simply telling them they're wrong is not going to correct the
problem, is it?

In any case, please stop posting until you have something
constructive to add.

cordially, as always,

rm

* Roger Maynard <whoknows@whocares.org> writes:

> Steve Youngs <sryoungs@bigpond.net.au> wrote:
>> A lot of it, yes, but on the other side of the coin, a lot of
>> documentation is right up to date, _and_ a lot of the old stuff is
>> _still_ relevant today.

> Most linux documentation is junk, written by high-school kids and
> college dropouts who seem to feel it is "kewl" to mispell at least
> half a dozen words per page of documentation.

I'd like to see you try to substantiate that statement. No, I'm not
suggesting that the majority of Linux documentation is of a high
quality, but I would argue that you are _vastly_ over exaggerating.

>> Being a newsgroup poster yourself, Paul, you are contributing to
>> the situation. I'll leave it up to the reader to decide whether
>> your contribution is positive or not.

> You're merely a cheerleader and as such, you do far more harm to
> the linux community than objective critics do. For you everything
> linux is good and as long as there are morons like you running
> around the faults of linux will not receive the attention they
> need in order to be corrected.

You didn't actually read what I wrote, did you? I can't think of any
other reason why you'd come out with such nonsense.

> pretending that all is rosy when it's not is clearly less than
> helpful.

Or maybe you just didn't understand what I was saying. Is English
your first language? Yes, that _is_ a serious question, because I
never suggested that "all is rosy". This is just something that you
have incorrectly assumed.

> Linux is free and yet Microsoft's installed base grows everyday.

Microsoft's installed base would grow everyday even if Linus Torvalds
had never been born. Microsoft's popularity doesn't have anything to
do with the existence, quality, popularity, stability, price, or
user-friendliness of Linux.

> Most people look at linux and see something not worth paying for.

Most of the people that I have spoken to about Linux (that are M$
users) have generally either:

a) never heard of Linux.
b) believed that it is a OS for programmers or über-geeks.

I guess there would be people who would look at Linux's price tag with
the attitude of "you don't get anything for nothing", and so they move
on. If you ever run into these people, Roger, send them my way and
I'll sell them a nice Slackware CD set for $450.00 a set.

> In any case, please stop posting until you have something
> constructive to add.

You should practice what you preach because even you do not believe
that your own posts are constructive. As evident by...

X-no-archive: yes

....that you add to your posts. You are so embarrassed by your own
ramblings that you don't want others to stumble across them some time
in the future.

--
|---<Steve Youngs>---------------<GnuPG KeyID: A94B3003>---|
| Ashes to ashes, dust to dust. |
| The proof of the pudding, is under the crust. |
|------------------------------<sryoungs@bigpond.net.au>---|

Steve Youngs <sryoungs@bigpond.net.au> wrote:
>> Linux is free and yet Microsoft's installed base grows everyday.

> Microsoft's installed base would grow everyday even if Linus
> Torvalds had never been born. Microsoft's popularity doesn't
> have anything to do with the existence, quality, popularity,
> stability, price, or user-friendliness of Linux.

That's right. It's a vast conspiracy led by Bill Gates.

>> Most people look at linux and see something not worth paying for.

> Most of the people that I have spoken to about Linux (that are M$
> users) have generally either:

> a) never heard of Linux.
> b) believed that it is a OS for programmers or ?ber-geeks.

Or c) know that it's an OS that doesn't run their favourite
applications, be they games, business apps, multi-media, and so
on...

> I guess there would be people who would look at Linux's price tag with
> the attitude of "you don't get anything for nothing", and so they move
> on. If you ever run into these people, Roger, send them my way and
> I'll sell them a nice Slackware CD set for $450.00 a set.

Why would they pay you 450 a set when it is advertised as being
free?

cordially, as always,

rm