Return-Path: wirzeniu
From: wirzeniu@hydra (Lars Wirzenius)
Date: Fri, 7 May 1993 11:57:30 EET DST
X-Mailer: Mail User's Shell (7.2.0 10/31/90)
To: linux-activists@niksula.hut.fi
Subject: Incremental publishing of the Sysadmin guide
Status: RO
X-Status: 

X-Mn-Key: doc

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.

--
Lars.Wirzenius@helsinki.fi  (finger wirzeniu@klaava.helsinki.fi)
   MS-DOS, you can't live with it, you can live without it.


.