I for one will agree that the documentation that ships with programs and
distributions could be better, with my one major complaint with man pages are
they do not allways include an example. Take sox for example, the man page
is very informative about what the program is, what it can do and all the
switches. However, there isn't an examples line, contrast that with the tar
man which does include some basic examples of usage. With that said, I have
found a good linux book can be indispensible. Back in 96 when I first got
involved with linux I bought "Using Linux second edition" and still find
myself opening that book from time to time. Actually the spine is shot and
cover is about to fall off.
There are many people out there who use linux and are not developers, and
many times I hear them say what can I do to contribute to linux. I usually
reply, if you encounter a "bug" contact the project and report it. Cruise
the list servers and offer help when to others when you can. Then the big
winner that I usually point out, projects need good documentation people.
Get involved, developers want to develop and will always welcome someone who
is willing to take on the documentation for a project.
That poses another challenge as previously mentioned, how do you keep up with
a moving target. I would say start with a "supported" version of a project
and get the core functions of the program documented, as minor releases and
patches come out release a "change log" kind of update for the documentation.
Then roll the changes back into the main document for each major release of a
program. Yes it's a lot of work, but if half the people who complained about
poor documentation contributed to it, the problem would go away.
On Tuesday 13 March 2001 00:12, David Rankin wrote:
> "tony K." wrote:
> > At 07:21 12-03-01 -0500 some list member(s) wrote:
> > >> My 2 cents worth as well. I am using cups with Mandrake 7.2/Samba
> > >> 2.07. It
> > >
> > >works
> > >
> > >> great. I have no idea how I got it to work, it just works.
> > >
> > >Ah, there is the problem. Anything is great when it works. Problem is
> > > when it does not work and figuring out "what" you have to do...
> >
> > The problem is not inadequate software. The problem is inadequate
> > documentation.
> >
> > Allow me to elaborate:
> > The documentation is usually written by the software developer.
> > He - as a general rule - just does not understand that the user
> > is operating in different ~operational~ and ~previous knowledge~
> > context. It is unfortunate that many a hard day's coding work
> > has been totally wasted by documentation which lacks
> > nothing but an intoductionary "Concepts and Facilities"
> > chapter.
> >
> > CUPS is no exception.
> >
> > tk
> >
> > Anthony K. Transportation Systems - no HTML mail please.
>
> My Observations and Experience:
>
> Alright, I started this ball rolling so I feel obliged to at least add my
> observation regarding the above. I think Tony has a very valid point
> concerning the sparseness of the documentation available to get you up an
> running with Linux/Cups or whatever. I was new to Linux as of January and I
> decided to take the plunge. I knew it wouldn't be easy, but I was willing
> to "pay the price" to learn. The Linux movement is one of the greatest
> things taking place in technology today. The OS is elegant and flexible and
> its capabilities are unmatched. That, in and of itself, is Linux's double
> edge sword.
>
> When I decided to take the Linux plunge, I was of course new to Linux.
> However, I was far from new to the computer world. I was involved in sewing
> JSC's lan together in Houston during the late 80's early 90's starting on
> 8086 machines, sperry Univax, etc. I have baby sat 750K lines of fortran
> assent simulation software (remember common blocks), programmed in
> assembly, C, Fortran, Ada, etc.. I have built PC's and written drivers
> starting with 286's when IBM DOS, PC DOS and MS DOS were arguing over who
> would win. Windows 286 - ME, NT, etc. So how much different could Linux be
> to make friends with?
>
> A LOT! Why? Because with just about everything else above you could pick up
> a relatively good manual or reference guide and have a reasonably good
> roadmap for the journey. Not so with Linux -- not a fault with Linux --
> just not so with Linux. The documentation that exists for Linux is
> scattered across the Linux World in a million different places, largely due
> to the number of core components of a Linux distribution being developed
> and maintained in at least that many different places as well. There are
> numerous basic Linux manuals available, however, none are relatively
> comprehensive as far a providing a good roadmap to get you through the
> maze. Most of the time spent learning
> Linux/Samba/Apache/DNS/Bind/DHCP/Sendmail/etc..(or at least getting it to
> work) is spent searching for the right Man page/How-To/Web site/Mailing
> List/etc... that has at least most of the information you are looking for.
> I say most, because no matter where you find the documentation, you
> invariably end up back at your favorite mailing list to find out "Oh, in
> addition to what the Man page/How-To and Web site said, you also have to do
> X,Y and Z." Again, this isn't a fault of Linux, rather it is simply a side
> effect of the open source concept and business model.
>
> How to solve this? Hmm - sounds like opportunity.
>
> There is no doubt that a comprehensive source of information can be
> distilled from the above sources. I mean, I got my net up and running,
> waded through the murky water, [I still haven't solved that pesky
> xntp/UTC/localtime/samba timeserver problem ;- ) ] and while I'm not
> entirely clear how I did it, it works, my logs are clean. The most
> frustrating part, going back to Tony's premise, was that the simplest
> problems took days to solve because there was no, or incomplete,
> documentation regarding the specific config or problem I was dealing with
> or there was nothing to point you to where the documentation was (save and
> except Google or whatever your favorite search is).
>
> Which brings me to my point (Thank God they say). Linux has reached the
> threshhold of going mainstream. Not only for corporate user with fat IT
> budgets, but for the small office masses as well. I think I have seen
> several threads from the list-admins acknowlegding that "We victims of our
> own success." (commenting on the massive increase of posting from new users
> seeking answers) The comment is perfectly true and all I can say is "Keep
> up the great work guys -- your doing one hell of a great job!" Linux is a
> great community with a lot of great people. Just like any society, its
> strength is in its numbers.
>
> If Linux is going to continue making headway increasing its market
> acceptance, a relatively comprehensive documentation system is a must. It
> must be somewhere where it can be found. LDP has started, and most of the
> individual distros and major component applications have their collection
> of knowledge, but a large part of it isn't in readily usable (or
> understandable) form for someone who is relatively new, and who needs the
> roadmap the most. Just a look into the /usr/doc directory of the current
> distros can be terrifying to say the least. For the masses to transition to
> Linux, it can't take 3 days of downtime to figure out where to look to
> begin to find out why the box isn't working.
>
> The answer -- Well that's the $24K question. How do you create a relatively
> comprehensive reference for a widely distributed open source project that
> is constantly changing? Surely, there must be a little VC left even after
> the market has tumbled that could fund the development of such a project.
> I'll leave it open for more discussion and suggestions and I will go back
> to practicing law which is an equally nebulous and poorly documented
> journey. At least now I have a server and net for my office that is utterly
> amazing to say the least. Oh, and one more observation, except for the
> electrical storm and associated power outage, not one reboot on the server
> has been required!
