Subject: Linux-Activists - DOC Channel digest. 93-4-7-9:16
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Fri, 7 May 1993 17:01:15 +0300

Topics:
	 Incremental publishing of the Sysadmin guide
	 Alpha Network Guide Out!

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

From: [email-masked] (Lars Wirzenius)
Subject: Incremental publishing of the Sysadmin guide
Date: Fri, 7 May 1993 11:57:17 +0300

I've been thinking about the LDP, and about my miserable track record
in particular.  One thing in particular that bothers me is that we
haven't produced much visible yet, even after months of (supposed)
work.  I know, there is a lot of work going on (there are a lot of man
pages, the KHG looks good, IS&GS is going on well, etc), but I think
that the lack of even alpha-level documentation is hurting the users a
lot.  Therefore, I'm thinking of publishing alpha versions of the
Sysadmin guide for everyone to read.  Essentially I would clean up the
chapters I've written so far and publish that, and then publish a new
version each time I finish a new chapter (or make significant changes
to an old one).

Note that I'm not proposing publishing seriously unfinished matter.  I
would only publish text that is supposed to be correct (both factually
and from a language point of view).  I would only publish things after
it had been "tested" by the DOC channel.  I compare this to the way
the Linux kernel is being developed: whenever Linus has changed the
kernel enough, he releases a new version, but not until he is
satisfied that it works, at least somewhat.  The result is obvious to
everyone: very rapid development.  Even though I can't allocate as
much free time as Linus, I think that this type of incremental
approach would still greatly speed up my writing.

(There is the problem of more overhead of handling people's reactions
and suggestions and questions, but I don't think it will become
unmanageable.  If it does, I can always say that I'm too busy to
answer all mail regarding this, and that I prefer to spend the time
writing instead.)

(Also, I'm not suggesting everyone do this: everyone has their own
style, and there _is_ the danger that alpha level documentation is
going to hurt more than it helps, and everyone needs to decide for
themselves whether they want to publish only final, polished versions.
I am only suggesting that I do this myself.  All alpha versions would
be very clearly marked as such: in large letters on the title page,
and in the header (possibly even the footer) of each page, as well.)

One specific example why the incremental publishing would be useful:
I've written a chapter on how to allocate swap space (it's not bad, I
think, although it needs some work yet).  This comes up on c.o.l every
now and then.  I'm too lazy to post the answer, but if at least alpha
versions of the SAG were available, more people would read it.

I'd like to hear your opinions on this.  I think it is a good idea,
but I'd like to hear somebody else's opinion as well.

My proposed publishing plan would be (the below more or less assumes
you have the pre-alpha version I put out on nic.funet.fi long ago):

	1. finish the chapters that are mostly written now
	   - Dividing the Disk
	   - Directory Tree Overview
	   - Boots, Shutdown, Logins, and Background Daemons

	2. publish those three chapters, plus an introduction that
	   clearly explains the alpha level nature of the thing

	3. then write and publish (more or less in this order)
	   - A Short Tutorial
	   - Kernel Configuration and Compilation
	   - Backups
	   - Users
	   - Ongoing Tasks
	   - Batch Processing
	   - Installing Software
	   - Discussion About System Administration
	   - Security and Safety
	   and whatever else that might be included

Please give me your opinion.

--
[email-masked]  (finger [email-masked])
   MS-DOS, you can't live with it, you can live without it.

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

From: Olaf Kirch <[email-masked]>
Subject: Alpha Network Guide Out!
Date: Fri, 7 May 1993 14:55:18 +0300

Dear Linuxers!

After so many advance laurels for it, I've finally put up
an Alpha version of it for your consumption. It is at 
ftp.stolaf.edu:/pu/linux-doc (if that's where Michael
has moved it). Please do not spread it around too much.

There are a source tar file, a dvi file, and a Postscript file.
All are gzipped. For your orientation, the README is appended below.

Some months ago, I started out with a single chapter on
UUCP for Lars' Sytem Admin Guide; in the meanwhile, the thing has
grown into a full-fledged guide of its own. In fact, it has
become quite voluminous - it's at 200 pages of Latex now.
Just to warn you...:-)

Finally, I'd like to lose a word or two on Getting the Docs Printed.
There has been some talk recently about conflicts of interest,
because the Linux guides cover things that have long been in other
books, and publishers have no interest in putting out two books
on the same topic. IMHO, the documents the LDP produces are
entirely different from what O'Reilly (or anyone else, for that matter)
publishes: their books go into detail a lot more than LDP
docs ever will. LDP docs are merely intended to bring information
to the _average_ Linux user - who is quite different from the
average Unix System Admin. For example, the NAG (hopefully) covers 
all aspects of TCP/IP and UUCP-based networking, for which 
O'Reilly has (at least) three books... But I don't think there's
a competition between these: If you want to do UUCP on your
Linux book, you won't buy a full-fledged guide like O'Reilly's;
and if you want to run UUCP as your main transport on a mail hub,
you won't settle for a peksy LDP guide:-)
That's what I think. No offense meant.

I hope you all enjoy reading the NAG, and send me _lots_ of
reviews, corrections, flames...

Yours truly
Olaf

---------------------- NAG README ---------------------------

Dear people!

This is version 0.2(alpha) of my networking guide for Linux.
It is not yet complete, some examples are still missing.
It's already quite close to Fred's net-2 release, using
the BSD-ish configuration commands.

It has grown pretty big; It's at 200 pages now. I hope
this isn't too verbose.

There are still holes in some places. There is no
sendmail documentation yet (only smail); Rich
Braun said he might write something on it.
There's no index either (look at the file 'index' for
an off-the-top-of-my-head list of index items).
Iain Lea proposed to put in a list of abbreviations
at the beginning; it could use more entries and better
explanations, too.

For other things I'd like to put in the guide soon, see
the enclosed TODO file.

Well, read it yourself... simply type 'make'. I hope
it will work.

There are two fancy pictures in it. I've produced them
with xfig, and translated them to eepic/Latex input.
You need the epic and eepic style files for this. 
Since they are not incorporated in the SLS release
of TeX (at least not the one I've got), I have
included them here. If your dvi printer filter
doesn't recognize the graphic specials, you might try
to convert the whole thing to Postscript. If your copy
of dvips doesn't understand the specials either, get
the PS file from this distribution. I translated it
using a relatively new dvips, which spews out a couple of
warnings, but gets the pictures right. I will have to look
into this...
However, using PS won't give you the Linux logo.
I didn't have any time to get and include it - yet.

Formatting now looks quite well in most places (thanks
to Michael K. Johnson's work!), but there are still a few
overfull hboxes. These come from {\tt /very/long/file/names}
and the like. To make them go away, I used the \sloppypar command,
which         gives         poor         spacing         on
some lines. These things will be fixed later

If you have suggestions/comments/complaints, mail me at
        [email-masked]
or      [email-masked]
Of course, cdiffs or udiffs are preferred:-)

Yours,
Olaf

--
Olaf Kirch      [email-masked], [email-masked]

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

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