Subject: Linux-Activists - DOC Channel digest. 93-4-6-20:6
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Fri, 7 May 1993 02:40:19 +0300

Topics:
	 Getting docs printed...
	 ORA - LDP connections

----------------------------------------------------------------------

From: [email-masked] (Andy Oram)
Subject: Getting docs printed...
Date: Thu, 6 May 1993 21:25:33 +0300

As I promised, here are my impressions of the kernel hacker's guide,
the sysadmin guide, and the uucp guide.  I hope this long mail message
will prove helpful to some people out there.  It can give you a
general sense of the difference between the Nutshell type of book we
like to put out, and other useful but less polished forms of
documentation such as functional specifications and FAQ's.

The kernel hacker's guide reminds me of a spec.  It starts with
something on the architecture (both of the software and of the 386),
then gets into a description of each subsystem.  I think this may be
what people need; some is useful for understanding performance or for
trouble-shooting, while some is just for peopole modifying the
kernel.  But this book is not shaping up into the kind of broad
tutorial that you find, say, in "The Design and Implementation of the
4.3 BSD Unix Operating System."  So we're talking here about a
collection of functional descriptions; I wouldn't say it's a guide.
Compare it for instance to the uucp document, which is clearly a
how-to guide.

I doubt that there are enough people modifying the kernel to justify
publishing the whole KHG.  But a significant subset may be useful for
understanding performance.  If someone wants to design a layered
system or application to make the best use of Linux, I think some
parts of this book would definitely help.  For instance, swapping and
paging might be sensitive to program behavior.  So some parts might be
good to publish.

I don't know whether it's worth writing a broader book on the BSD
model, containing more of a description for beginners plus the
philosophy of the development effort.  Tell me what you think.

Now for the uucp guide.  I don't know much about uucp, but this looks
full of information.  It's a traditional guide, and seems to meet its
goals.  Unfortunately, it runs into a conflict for me, because as we
all know, O'Reilly already has a uucp guide.  I think we'd want to
incrementally change our existing guide, and adapt it for Taylor uucp,
instead of putting out your guide.  Them's the breaks.

Finally, the sysadmin guide.  This is half-way between the spec-like
structure of the KHG and the guide structure of the uucp book.  There
are already some valuable chunks of information there, and I can see
from the notes that Lars is planning more useful stuff.  But I'm not
sure it will end up as a beginner's guide.  It looks more like a FAQ
(but more carefully written and more thorough).  That is, you browse
the book to find a topic you need to learn about, and then you a get
some useful tips.

I think you could turn the sysadmin book into an O'Reilly sort of
guide.  You have to add a lot and organize it carefully -- this may be
more work than you want to do.  Somewhere, you have to tell people
what the job of system administrator entails, give an overview of the
system and network and the sysadmin's role in keeping them up,
describe what can go wrong and how to investigate it, etc.

Luckily, this book can be smaller and simpler than the typical UNIX
system administration books on the market, because Linux is mostly
used as a single-user system, and you don't have to get into issues
like disk quotas and backup policies.  Networking is usually much
simpler too.

If the sysadmin book remains a collection of tasks and procedures
(more a FAQ than a guide) I still might support publishing it because
the pieces of information is very useful.  But people usually expect
more than this of a published book.  They want a good flow of ideas,
general introductions to concepts, and so forth.

----------------------------------------------------------------------
Andy Oram O'Reilly & Associates, Inc.  [email-masked]
             90 Sherman Street, Cambridge, MA 02140     (617) 354-5800
                                                    fax (617) 661-1116
----------------------------------------------------------------------

------------------------------

From: <[email-masked]>
Subject: ORA - LDP connections
Date: Thu, 6 May 1993 23:28:18 +0300

[Please pardon me if this ends up in the wrong place....first times are fun.]

Another thing in favor of O'Reilly publishing some of the books is the places
where O'Reilly books end up.  My company has been the only computer company
in town actively pushing O'Reilly or linux.  We don't deal with ANY other
publishers becaues O'Reilly has been so approachable and reasonable.  Just as
DG made the ORA X books a standard part of their doc set, I'd like to be able
to give a user a book from ORA rather than something I Xeroxed 8 million of
and bound at Kinko's.  No disrespect for PH intended but the ONLY company
which has consistently been UNIX's best friend is O'Reilly.  I don't know how
many computer shops are similar to mine, but I'm sure a lot of others would
be much happier and would respect a lot more an ORA product.  My interest is
seeing a high quality product getting to people.  linux is.  The LDP is
moving in the same direction faster than I can believe.  And ORA would complete the package in a high quality way.  (Who'd have thought that all those
hackers would make the best OS and the best docs ever?)  

-chris

------------------------------------------------------------------------------
"Free software isn't free, but expensive software is expensive."
------------------------------------------------------------------------------

------------------------------

End of DOC Digest
*****************
-------