[Novalug] documentation

[Gary Knott]

Written specs prior to programming are okay to have
as long as you don't invest a lot in writing them.
Actually though, a draft user's manual is a good thing to write
prior to coding.

It is very important, however, to keep the design documentation
semi-up-to-date as the project progresses.
(e.g. data-structure definitions, relational table
layouts, list and meanings of reusable subroutines, etc.)

In my not-so-humble opinion, the code should be carefully
documented by using comments IN PLACE, so that the code and
programmer's documentation goes together.

See the "how to write computer programs" page at
www.civilized.com  (just scroll down and select it.)

Then there should definitely be a careful and complete
user's manual (or maybe several, each at different levels)
that tells the purpose and functionality
of the program, more than a bit about how it works,
definitions of terms and concepts, and A LOT
about how to control it.  Also, a list of
files used and where they are, and any other
depepndencies need to be given in a special
installation and how-to-update chapter.

The assumption that programmers are either
bad writers, or lazy, is no excuse, and, anyway,
are wrong in my opinion.  It is disrespectful
to users to make them struggle to learn
how to control a program.  Just look at all the
problems people have using software - Linux, Windows,
OSX based, it makes little difference - due
to non-existent - or inaccessible - or incomplete
documentation.

(There are many programs I would
like to use, or like to learn how they work,
e.g. Myth TV or alsa - but I am unwilling to
invest a lot of time in struggling to do so.  If the
authors don't care about this, then they have
no responsibility to provide a manual - but
if they do care, as most of us do, how are users
expected to learn to use and really understand
a program without a book?)

Look, for example, at the GCC compiler.  Most
of us using it, have little idea about its
copious controls, and even if we check
easily-accessable documentation (man-pages)
we still have little appreciation for
what gcc can do, nor what the inputs and outputs
can be - what is an .elf file, what is its
internal format - how do we use gdb -  what are
.so files, what are the tricks in using them, and
so on. where are the header files?

There are several books on gcc.
The one I have is poor, and I have never seen
a copy of the GNU foundations's book, nor a
downloadable copy of it.

On the otherhand, look at emacs - there is
a downloadable manual of about 600 pages available.
It may be more than you want to know about
emacs, but it is very valuable when you need
to find out about some obscure issue
like how do you control obstreperous
"style" macro packages (like .c vs. .txt)
or if a matching paren-checking feature
exists and how to use it.  (or what about
finding and replacing non-printing chars
like 0x231 or 0x221?)



-- 
==============================================================
| Spoken: Gary D. Knott      Email: knott at civilized.com       |
| Phone: (301) 962-3711      MIME mail welcome                |
|                                                             |
| web: www.civilized.com  (Please look at our HomePage!)      |
| USPS: Civilized Software Inc., 12109 Heritage Park Circle,  |
|       Silver Spring, Maryland 20906, USA                    |
==============================================================