Date:	Tue, 6 Jun 1995 17:29:13 -0400 (EDT)
From:	Ken Bowen <ken AT jarrett DOT als DOT com>
Subject:	(NO) CODE STANDARDS/ (YES) DOCUMENTATION
To:	djgpp AT sun DOT soe DOT clarkson DOT edu

At the risk of throwing ethanol on burning gasoline,
let me make some observations and comments, with the
pious hope that some might be seen as constructive.

Obs#1: There are distinct subcommunities within the DJGPP 
readership whose individual goals are sometimes at cross
purposes.  Given individuals sometimes inhabit more than
one camp. In particular, there are those who are primarily
interested in implementation of DJGPP (the extender, gcc,
etc.,etc.), and those who are primarily interested in 
using DJGPP in personal or professional projects.  [I myself
fall into the latter (apply it) for DJGPP, but into the
former (implement it) for the Prolog compilers I use 
DJGPP to build. ]  Each group really needs the other:

A.  Not many compiler builders find it much fun it there
    aren't any people using their tools.
B.  Obviously, a compiler user needs some compiler builders,
    unless he/she is inhabiting both camps.  And then it is
    still more fun to play in a sandbox with other kids.

So: Mutual symbiotic co-existence is the order of the day.

Note on good manners: Both implementation and application
are "real" work.

Obs#2:  There is a wide variation in individual ability to
maintain detail in one's head.  That is, some of us have
more need for documentation than others.  (I need more.)
I've observed this "fact" and the variation in sytle/need
in every project I've been involved with, including all of
the work at this company.

Obs#3:	Good documentation is always valuable, for all of
the reasons that various people have brought out, but most
importantly: communication between programmers.  Almost all
of the other good things that flow from documentation can be
seen to flow from good communication between programmers.

Obs#4:  Communication builds community.  The on-line DJGPP
community is very pleasant _AND_ very productive.  This
has come about already without any great documentation effort,
which says good things about the people involved.  Developing
more extensive documentation would enable that conjenial
community to expand a little bit more easily.  [Let me comment
that the Prolog on-line communitiy is neither so conjenial
nor nearly so productive. In part, it is not so focused, but
that doesn't account for everything.]

I'll end the high-level observation/pontification here.  I have
a few more specific concerns and questions related to documentation.

DJGPP (on DOS; hopefully on 32-bin MS Wins and OS/2), and GNU
on Unix, is the tool we've used to build ALS Prolog, and is
the primary tool that our users will use to extend Prolog programs
with C-stuff (interfaces, etc.).  So I've been mulling on what
I could do to produce more of a "traditional" manual for people
who (like me) are not the world's hottest C programmers, though
usually they are hotshots at other things ranging from chemistry
to risk analysis.  The FAQ and the Info pages are a good start, 
but in both My Humble Opinion, and my experience supporting my
users, not quite enough.  What I envision would still be 
small and crisp, but do a bit more (linear) handholding, with
good hypertext support.  Perhaps it would be possible to
start from the current FAQ and Info pages, and stitch
them togehter with some editing/expansion, and just plain new
hand-holding material.

At ALS, we are moving from using hard-copy manuals to using on-line
manuals.  We are using the Adobe Acrobat reader for distribution
because it is both (economically) free and available on a fairly
wide range of platforms, including DOS with a very high-quality
GUI presentation.  It provides very nice PostScript and HyperLink
connections.  Unfortunately, even though the readers are ($) free,
the tools to develop things are not.  Realistically, one has
to either invest in Adobe's Acrobat Distiller, or in the 
forthcoming version of FrameMaker.  [For our historical sins, we have 
done both.]  It is possible to convert between various of these
Publishing formats, including TeX, but not at all easy.  
We use FrameMaker to prepare our manuals.  Until this month (6/95),
we had to do fairly arcane things to get the source transformed to
Acrobat, but one would never want to prepare source in Acrobat.
When the new version of Frame comes out this month, it will produce
Acrobat, so it will make such things fairly nice.  It can also
produce PostScript (no hypertext there), and HTML, a very nice
alternative, but to my eye, not as nice as reading PostScript.

One other note.  As I understand it, Adobe has no plans for further
development of the DOS version of Acrobat.  On the one hand,
this is unfortunate, in that it doesn't support cross-document
hyperlinks, as the Windows and Mac versions already do, and which 
Adobe says the next Unix versions will.  On the other hand,
it might possibly be fortunate.  I've thought about approaching
Adobe and encouraging them to put the DOS version in the public
domain, much as QuarterDeck has done with some of its stuff.  This
should be a win-win move:  The DOS-based public domain/free software
community would gain a powerful documentat presentation tool, and
Adobe would gain (presumably) an on-going improvement of the 
Acrobat reader.

Sooooo, I'll put this out, inviting comments, flames, suggestions, 
offers of help or cooperation, etc., etc.

|| Ken Bowen      Applied Logic Systems, Inc.         PO Box 180,     
||====            Voice:  +1 (617)965-9191            Newton Centre,
||                FAX:    +1 (617)965-1636            MA  02159  USA
                  Email:  ken AT als DOT com        WWW: http://www.als.com

- Raw text -