Subject: Re: doc.status
From: wirzeniu@klaava (Lars Wirzenius)
To: [email-masked]
Date: Tue, 5 Jan 1993 03:13:16 EET

X-Mn-Key: doc

doc.status                                         -*-Outline-*- 
Status of the Linux Documentation Project
Lars Wirzenius

Version: $Id: doc.status,v 1.2 1993/01/05 02:58:08 liw Released liw $
E-mail to [email-masked].

* Ramblings

        A few comments on things that have cropped up on the DOC
        channel.  Sorry about not responding to individual comments; I
        _hate_ the digesting.

** Book printing

        Some time ago arl suggested that cheap printers in China (I
        think it was) could be used to provide inexpensive hardcopies.
        The quality isn't going to be that great, but at least it is
        printed and bound (therefore probably often more convenient
        than a large binder), and should be cheaper than printing out
        everything on a laser; I think he's said something along the
        lines of about 5 dollars for a book of 500 pages to be
        possible.  I'm not aware of the details, but the price price
        seems good.  For that price, it might even be possible to
        print a new version every year or even every six months (we
        might not even have to wait until the whole doc project is
        finished until the first printing).  What do you all think?
        Does anybody know of cheap printers?

** Version control

        Version control is unpleasant, but important, even necessary.
        I propose the following (natural) scheme: Each independent
        part of the documentation (see below for my standard list) has
        its own version number, and that part is released and its
        version number issued by its maintainer/coordinator.  The
        whole documentation set also has its own version number,
        issued by the project coordinator (me).  Basically, the
        version number of the whole set identifies a set of documents
        and their version number that form a coherent, integrated
        whole.

        The way I envision it, each independent document is written
        and maintained independently, but with feedback going from
        everybody to everybody so that all parts fit together.  When
        the coordinator of a document so wishes, he puts out an
        "alpha" version for others to comment.  This version gets a
        unique version number.  He gets feedback, edits, and puts out
        a new version.  This is iterated as necessary.  When a version
        is considered "finished", it is released "for real".  When
        enough "for real" versions of various documents are out, a
        "for real" version of the whole set is released, and given a
        version number.

** Copyrights

        Linux is copyrighted with the GNU Public License, as are most
        of the standard utilities, the compiler, and so on.  Some
        stuff is from BSD, and uses their copyright.  Other stuff has
        its own copyright.  All in all, it is a bit of a mess, but
        everything still seems to be freely usable, modifyable,
        distributable (even for cost), and generally aren't
        troublesome for most people.  [No flames about how the GPL is
        a pain in the ass for people who want to do commercial stuff.]

        The documentation set should, nay must also be just about as
        free.  It would be nice if as much as possible used the same
        copyright, to reduce the legal complexities.  I'm personally
        leaning towards something along the lines of what the UUCP
        document draft in nic.funet.fi:.../ALPHA/doc-project uses,
        that is the GPL with the relaxation that hardcopy distributors
        do not have to provide the source code.  Or perhaps something
        like the BSD copyrights.  This needs to be discussed.

        Another legalistic question is who should own the copyrights.
        Should we have one copyright holder for the whole set (except
        for stuff that is already copyrighted, for example existing
        man pages), or should each author own what he produced?  I
        prefer the latter, and I doubt that there is much
        disagreement.

** Typesetting

        There was some discussion about supporting both letter and A4
        size paper.  This is important, but I think there are more
        sizes than that: for example, it might be convenient to use
        paper that is about half of those sizes since the book or
        binder (or whatever) is not as big.  Also, if somebody wants
        to use ghostview to look at the documentation, it's probably
        nice to not have the whole screen taken over by it.

        However, I always thought that LaTeX took care of most of the
        details of adapting to different paper sizes: you just have a
        setting in one of the .sty (or whatever) files that specifies
        the paper size (explicitly or implicitly), and the formatting
        algorithm takes care of the rest.  Well, I know there is more
        to it than that, some stuff has to be typeset and laid out by
        hand, but I always thought that was only a small part of it.

        If I'm right, then the important thing is for each writer to
        make certain that he doesn't make the document difficult to
        format for different paper sizes by embedding knowledge or
        assumptions to his LaTeX source code (or whatever he uses).

        Perhaps some of you who have more experience with typesetting
        (hopefully we have or can reach such people :) could comment
        on this?

        For whatever it's worth, I personally prefer the more
        restrictive and "calm" style as is used for example in K&R to
        the "hey-this-printer-has-*34*-different-fonts" style that has
        been used in at least some of Borland's manuals (I remember a
        paragraph where about every third or fourth word was in a
        different font than those surrounding it).

* doc-project directories at nic.funet.fi

        Arl has kindly created 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.

        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.

* Short outline of Linux docs

** Getting Started

        The be-all and end-all of Linux installation instructions.
        Covers installation and has brief tutorials on using and
        administering Linux.  This book is all that a novice should
        have to read in order to get going.

** User's Guide

        The full story of how to use Linux, except for individual
        program usage.  (That is, the UG covers usage in general, not
        specific program in particular.  The Reference Manual is for
        that.)

** Administrator's Guide

        How to keep Linux up and running after it has been first
        installed.  Installing new software, doing backups, etc.

** Programmer's Guide

        How to write programs under Linux.  Not urgent.

** Local Guide

        This is mostly for systems with many users.  Similar to the
        LaTeX Local Guide.  Summarizes differences between the real
        system and the "generic" systems described in the rest of the
        documentation.  Things like lists of hardware, local hacks,
        installed software, etc.

** FAQ

        This one everybody is hopefully at least vaguely familiar
        with.

        Idea: In addition to the Linux FAQ, include other FAQs as
        well, like those for Unix, C, PC hardware, UUCP, news, etc.

** Reference Manual

        Manuals for programs and so on.  Man pages, texinfo documents,
        etc.

** Linux Kernel Hackers' Guide

        Kernel documentation.  Essentially tells how the kernel works
        so that hackers can hack it easier.

** Linux Readings

        Miscellaneous other Linux related documents that don't fit
        into other books.  Things like my interview with Linus in
        Linux News #3, a history of Linux (everybody urge Linus to
        write it, my urgings aren't working :), Who's Who of Linux, a
        Linux bibliography.

** Global Index

        An index that covers all other manuals, to make it easier to
        find things that are covered by many manuals.

* Format of documents

        It seems that LaTeX is what most people favor.  However, each
        writer should use whatever format he finds comfortable,
        although using the same thing everybody else uses creates less
        confusion.  The important thing is not to flame about the
        format, but to get things done.  Once we have good text in
        some format, we can convert it.

        Michael Johnson has a set of typesetting guidelines that
        writers are encouraged to follow.

* Slaves (a.k.a. volunteers)

        The e-mail address and full name are followed by a list of the
        tasks the person has done, is doing, is committed to do,
        and/or has expressed an interest in doing.  Status information
        is indicated in brackets.

        If somebody is mentioned as a coordinator for a document, that
        usually means they will probably write much of it as well.
        Except that I'm not going to write most the doc project as a
        whole :).  For those parts that do not have their own
        coordinator, I will serve as one, but this probably means only
        that I'm looking for volunteers to take over that part of the
        job.

** [email-masked] (Lars Wirzenius)

        Coordinator of the doc project in whole.
        Intro to sysadmin in Getting Started [outlining].
        Administrator's Guide [outlining].

** [email-masked] (Matt Welsh)

        Coordinator of Getting Started [outlining/writing].
        INFO-SHEET [posting regularly].

** [email-masked] (Larry Greenfield)

        Coordinator of User's Guide.
        Intro to using Linux in Getting Started.

** [email-masked] (Michael K Johnson)

        Editor and co-author of the Kernel Hackers' Guide [working on
	it].
        Style guide and LaTeX .sty file for typesetting the docs
        [working on it].

** [email-masked] (Dan Miner)

        Co-ordinator of the Kernel Hackers' Guide [working on it].

** [email-masked] (Gavin Thomas Nicol)

        Coordinator of the Reference Manual.
        Man page to Texinfo conversion program.

** [email-masked] (Owen LeBlanc)

        Proofreading (spelling and grammar checking).  [offering
        services]

** [email-masked]

        "I could write some basic stuff ... on setting up uucp and/or
        mail".  [offering services]

** [email-masked] (Karl Fogel)

        Intro to Unix for ex-DOS users (to be part of Getting
        Started).

** [email-masked] (Piers Cawley)

        Proof reader [offering services].