Proposal for a change in documentation

[John D. Coleman]

I apologize to any die-hard *nix fans for sending this using Windows but
I give up on getting Linux installed on my system after trying to read
Sendmail's documentation.
I can use Slackware and probably will for now. I just need to figure out
what the distributions' maker has done because it was a real pain to get
internet access using it.

I'm sending this to address@hidden because I found a standards
document in autoconf that led me to believe that this should be sent
there, and because gnu.org seems to be a major source of Linux software
and a push for better documentation from you would help greatly,
To: address@hidden because I _think_ that that is the source of much
of the generic instructions that I have found in a lot of source files,
To: address@hidden because (UNPRINTABLE). Let's just say
that it was your docs are what prompted me to actually sit down, think
this up and send it.
I'm going to find, for now,  a program that I saw once that could
send/recieve/distribute mail. It was only one program.

I was trying to get internet access through Linux and get X installed
before seeing if there was a program that I could write that maybe
someone could use. But while trying to compile
the programs required for my use, I encountered major difficulties in
doing so. That pointed out what I see to be a need for me to do
something else instead.

I am not a systems engineer, systems analyst, or anything else similar.
I have however been exposed and tinkering with x86 computers for a long
time and I figure that if I am having this much trouble then I'm left
wondering how much trouble it would be for someone else with less
experience than me to follow instructions and install various programs ?

I've only spent about 6 or so hours thinking up the exact format of what
I think should be done but I have been thinking about it for the last
several months.

So I would like to know what you think. What follows is a proposed
template for installation documentation. The goal is to make it
structured and easy to follow. I.E. To make it dummy proof. Well, maybe
not that far. Pretend that you are a bug crawling along a frayed hemp
rope that is suspended over a fire. You want to start at one end and
reach the other end without falling off.  Once you start, you might
follow some branching strands of rope-those branches take you right back
to where you left the main rope, but if you keep going and don't fall
off, you will eventually reach the end.

Counterproposals, comments are requested.

The comment that these programs are free and are provided out of the
goodness of the authors hearts and that I don't have that right to
demand better documentation will NOT be acceptable ! I do not have the
right to demand but I DO have the right to make a polite request and to
provide user feedback so that is what this is.

I could keep quiet, write my own HOWTOs, start a web site, etc. But a
lot of HOWTOs would be unnecessary if only the documentation can be well
written at the source.



Note to program authors:
Since I didn't design the program that you have provided, I can only ask

very nicely that you consider changing the format of your documentation
to
what I have proposed here or come up with another format on your own to
try to make it easier on people who do not have an in-depth
understanding
of your program.

I will not promise but I will try to take the time to re-format your
documentation for you if you wish. ( BIND is not included in this offer
!
Those docs are very extensive. And this offer pretty much only applies
to
those programs that I am interested in or are trying to install myself.)

Because I do not have your expert knowledge of your program, I would
then
need your help to make additions, corrections, etc as would be required.

I am not an english major. Speaking of english, need to find a way to
make
these instructions in other languages. Possibly generated on the
installers
system. Or is that not needed ? If it is, is there a translating program

available ?

One of the reasons that is prompting me to do this is what seems to be
GNU's
autoconf's documentation format. While having generic installation
instructions
is a good thing, it should NOT help to encourage what I perceive to be
fragmented documentation. Having to read several doc files to find out
what
programs are required to compile another program is nuts !

I can understand my calculus book better than some of the docs that I've
seen.

Many people after they design a program just want to get it out the door

as quickly as possible. The author then `tacks on' other documents that
are particular to that program. That makes for some badly structured
documentation.

A template should be provided with a set format that has generic
instructions
that can be edited as needed but that also provides room to insert
instructions particular to the program being provided.

Because this file is a template, comments to program authors start with
a `#'.
Everything else will be in the finished product.

Proposed format follows:


                            (Program name)
                         (Program version #)
                                 by
                         (see the file: AUTHOR)
                         (Source: www/ftp)



Program Description:
# IE: What is this program for ? Do NOT include details.
# Example:
Sendmail is a program to send mail from this host to another host
on a network.
# A security library file.
# etc.



Supported Platforms:
# List of systems that this program will operate on.



Files that will be automatically installed by `make':
# List files/directories that will be installed so that the installer
will
# then know where a particular file originated from.
# Files and directories can change due to installer options so try to
list
# them generically: (PREFIX)/blah
# If you can not list them all, please include a note stating that fact.




Files that the installer (that's you, the reader) must create to operate

this program properly:
# List configuration and other files that WILL be or MAY be required to
be
# created by the installer for proper operation of this program.
# List only those files that will be outside of the installation
directory.
# Do not list files created in the sources' directory.



Supporting files or libraries that are included with this program:
# List libraries, etc that are needed by this program due to their
version #
# i.e.: this program is linked against glibc version 2.2 therefore
# it is included.
# My two cents:
# Including these files is in my mind a VERY bad idea because then the
# installer might then have two or more copies of a file but in
different
# places. (X and/or Gnome seems to do this.)
# It is better to direct the installer to get and install a particular
# version of a file himself and store it where he wishes
# If you are concerned about these files not being available from their
# originating site, then how about storing them with this program on
your site?



INSTALLATION INSTRUCTIONS:
The instructions that follows has been designed to be read and performed

in the order in which they appear.



Sequence of events:
1: Pre-installation - Requirements to be met before installing this
program.
    a: Read supporting documentation. ie. license, FAQ, etc.
    b: List of required or recommended files to be already installed.
2: Theory of operation - This is needed so that the installer will
hopefully
    understand what is needed to install and configure this program
properly.
3: Install - How to install this program.
    a: List of add-ons that you might want to include and why you might
want to.
    b: Installation instructions.
4: Configure - How to configure this program for use.
5: Testing
6: Use - How to use this program.



1 - PREINSTALLATION
    a - Please read any license, FAQ, BUGS, etc. before continuing and
    refer to those documents as needed while installing because you
might
    have to change what you have to do to install this.
    Read the FAQ for instructions on how to submit a bug report or for
    directions on where to go to for help or further information.

    b - Before compiling this program, the following files are REQUIRED
or are
 RECOMMENDED to be already installed on your system. Please refer to
 the individual programs' documentation for instructions of how to
 install them:
# Note which are required and which are recommended.
# (Though that can change depending on the installers system.?)
# System specific files that vary according to the installers system.
# Files to generate documentation.
# Files for security.
# etc.
# Include every file that you can think of; glibc,termcap, etc.
# (I think that you can skip the having a computer and a kernel part)
# This list can be difficult to make due to assumptions.
# DO NOT include instructions on how to compile those programs.
# (It seems that a lot of people like to include instructions for how
# to compile the linux kernel.)
# DO mention optional add-ons for those programs that are needed
# by this program that should have been installed along with those
# programs. Example : ncurses support.
# Tell the installer to go back and install those add-ons if needed.

    c - Preinstallation is complete. Continue by reading the file:
INSTALL



List of other recommended documentation files (not complete):
NEWS - outlines new features
ONEWS - list of features in older versions. This is a continuation of
NEWS
BUGS - Lists current but not yet fixed bugs
CREDITS - credits
TODO - should this really be a separate file and not part of BUGS above
?
AUTHOR - List of present and past contributors to the program
ChangeLog(s) - List of changes
Change the file COPYING to LICENSE - Put the license, disclaimer, etc
here.
PREINST - Preinstallation instructions
THEORY - Detailed description of the program
INSTALL - Installation instructions
CONFIGURE - Configuration instructions
TEST - How to test the program
USE - How to use the program. In the case of BIND and others, this might
not
be an actual file but there should be a reference to where to find this
documentation at the end of the installation process.
README.1ST - This file
FAQ -
# Put instructions on how to submit a bug report and directions on where
to
# go for help or for further information at the beginning of this file !

# As in: Make them questions #1 & #2
# #3 List of mirror sites.
(Other files as needed) - But they MUST? be referred to somewhere in
this
installation guide.

If any files MUST have a license appended to it why can't the files just

refer to the LICENSE file instead of having the entire text repeatedly
copied?