Subject: Linux-Activists - DOC Channel digest. 93-0-24-11:20
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Sun, 24 Jan 1993 16:03:43 +0200

Topics:
	 newbie.blurb

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

From: Lars Wirzenius <[email-masked]>
Subject: newbie.blurb
Date: Sun, 24 Jan 1993 13:12:12 +0200

My posting on comp.os.linux.announce attracted a few more new
volunteers.  Instead of writing a personal reply, I wrote this.  I'm
sending it to you too to make sure I get flamed if I forgot something.

---snip---
newbie.blurb				-*-outline-*-
by Lars Wirzenius

$Id: newbie.blurb,v 1.1 1993/01/24 13:03:25 liw Exp liw $

	This is a standard response that I send to all new Linux
	documentation project volunteers.  The purpose of it is to
	explain where we are now, how we work and communicate
	toghether, and what else you need to know.  Sorry about the
	impersonal message, I'm just too lazy to write something
	different for everybody.  Also excuse me for the size, I tried
	to cover everything important and it grew bigger than I first
	intended.

	(This is in GNU Emacs outline format to make it easier for me
	to edit.)

* What we are trying to do

	The doc project tries to create a set of good, well-written,
	and comprehensive manuals for Linux.  The documentation will
	be freely distributable, although the exact copyright details
	are not clear yet.

	As a side effect, the documentation set should be usable with
	other Unices (free or otherwise) as well.

* What will be included

	The documentation will be broken into several parts:

	Getting Started (installation, brief tutorials on using)
	User's Guide
	Administrator's Guide
	Reference Manual (docs for specific programs; man pages, texinfo)

	Programmer's Guide (not urgent)
	Local Guide (local conventions; mostly for multi-user sites)
	FAQ
	Linux Kernel Hackers' Guide (docs for kernel programmers)
	Linux Readings (misc. other Linux docs: Linus' interviews, etc)
	Glossary
	Global Index (covers all manuals)

	For more information, see the doc.status posting that I post
	every now and then to the DOC channel.

	At the moment, the first four parts are the urgent ones,
	because they are what are needed most.

* How we work

	At the moment, people are mostly hiding somewhere and writing
	stuff.  When something is written, it should be put into
	ALPHA/doc-project (see below) and announced on the DOC channel
	(see below), so that others can take a look at it.  (If you
	are not on the DOC channel, you'll miss these announcements.)
	People who want to proof read can then get the manual (or
	whatever), proof read it and send their comments back to the
	author.  It can be a good idea to send me and the author a
	note before you start, so that we know what is going on.

	When the manual is finished, or at least finished enough to be
	distributed more widely, it should be put into doc/doc-project
	(see below) and announced on comp.os.linux.announce.  This
	will make it available to the general public.

	The author can use the ALPHA/doc-project phase either as a
	quick sanity check, or as a way to get the thing absolutely
	right until published.  The former way has the advantage that
	it gets things faster to the hands of the users, and the more
	users a manual has, the more feedback it is going to generate.
	The latter way, on the other hand, will make more people happy
	with it and will generate fewer complaints about the poor
	quality.

* The DOC channel

	The main forum for discussion is the DOC channel on the
	[email-masked] mailing list.  Send a dummy
	mail to [email-masked] to get
	instructions on how to join.

	To avoid putting unnecessary stress on the mailing list
	machine, it would be nice not to join, unless you are going to
	actually do some work, not just listen to what's going on.

* Sharing files: nic.funet.fi: /pub/OS/Linux/ALPHA/doc-project

	There are two directories for the doc project on nic.funet.fi.
	The first is /pub/OS/Linux/ALPHA/doc-project.  This is meant
	as a place where unreleased stuff can be shared among the
	people who do the work.  For example, when somebody has
	written something and wants people to comment on it, and feels
	that it is too big to send via mail, it can be uploaded to
	.../ALPHA/incoming, and arl will move it to
	.../ALPHA/doc-project (send him a note about it so that he is
	certain to know what it is and where it should go).

	I repeat, .../ALPHA/doc-project is not meant for public
	consumption.  Don't encourage people not willing to work on
	the stuff there to grab things from there.

* Publishing files: nic.funet.fi: pub/OS/Linux/doc/doc-project

	The other directory, .../doc/doc-project, on the other hand,
	is explicitly meant for everybody.  Stuff that is finished
	goes there.  Actually, it doesn't even has to be finished: if
	the author thinks it is good enough to throw on unsuspecting
	people, it should be put to .../doc/doc-project.

	As far as I know, none of these directories are mirrored
	elsewhere.

* doc.status posting

	I post, every now and then, a document called doc.status to
	the DOC channel (and a shorter version to
	comp.os.linux.announce).  This attempts to give some picture
	of what is going on.

* Format and writing tools

	LaTeX seems to be what most of the writers prefer, so that's
	what they use.  There is no hard rule about this, and any
	format is welcome.  It is more important to get something
	written; when it exists in some format, it is more or less
	easy to convert it to other formats.

	We will provide pre-formatted versions at least for the most
	popular output media, including PostScript, Laserjet, and
	plain ASCII.  If possible, we will also write a tool to
	convert the LaTeX source to Texinfo source so that it be
	easily browsed with the GNU Info system.

* About the time table

	There are no hard deadlines for this project, since it is all
	done by volunteers with better things to do.  The only way to
	speed it up is to do things yourself.  However, we hope to
	have something ready any century now.

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

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