X-Authentication-Warning: delorie.com: mailnull set sender to djgpp-workers-bounces using -f
Date: Tue, 22 Jan 2002 20:37:43 +0200
From: "Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
Sender: halo1 AT zahav DOT net DOT il
To: dj AT delorie DOT com
Message-Id: <2427-Tue22Jan2002203742+0200-eliz@is.elta.co.il>
X-Mailer: emacs 21.2.50 (via feedmail 8 I) and Blat ver 1.8.9
CC: jeffw AT darwin DOT sfbr DOT org, djgpp-workers AT delorie DOT com
In-reply-to: <200201221757.g0MHvKw23453@envy.delorie.com> (message from DJ
	Delorie on Tue, 22 Jan 2002 12:57:20 -0500)
Subject: Re: djgpp user guide in Texinfo
References: <20020121153543 DOT A15018 AT kendall DOT sfbr DOT org> <4331-Tue22Jan2002111605+0200-eliz AT is DOT elta DOT co DOT il> <200201221414 DOT g0MEEDG21678 AT envy DOT delorie DOT com> <7458-Tue22Jan2002185340+0200-eliz AT is DOT elta DOT co DOT il> <20020122114417 DOT A15458 AT kendall DOT sfbr DOT org> <200201221757 DOT g0MHvKw23453 AT envy DOT delorie DOT com>
Reply-To: djgpp-workers AT delorie DOT com
Errors-To: nobody AT delorie DOT com
X-Mailing-List: djgpp-workers AT delorie DOT com
X-Unsubscribes-To: listserv AT delorie DOT com
Precedence: bulk

> Date: Tue, 22 Jan 2002 12:57:20 -0500
> From: DJ Delorie <dj AT delorie DOT com>
> 
> The division among the three documents, in my mind should be like this:
> 
> UG - assume nothing you haven't already covered in previous sections,
> act like a tutorial, gloss over "why" in favor of "how".  Very
> procedural.
> 
> KB - Cover the "why" here, with all the gory details.  No need for
> continuity, but each topic should be complete.  Good place to stash
> the odd useful email or two.
> 
> FAQ - Shortcuts to things that are often asked, even if they're
> already documented.

I agree about the FAQ -- it should be a subset of the other documents,
mostly of the KB.  As for the other two, I had a slightly different
dream:

User Guide should be just that: a guide; a document that new users are
supposed to read and whose steps they follow as they learn to use the
package.  It should have chapters like "Installation", "Setup",
"Documentation", "Compilation", "Profiling", "Debugging",
"Troubleshooting", etc.  Each chapter should simply describe, step by
step, how things are done, assuming the ``normal'' course of events
(no crashes, no unresolved externals, etc.), except in the
Troubleshooting chapter (which should be limited to the most
``popular'' and frequent problems).

Knowledge Base should be a collection of specific problems and their
solutions.  Lots of this is spread all over the FAQ, sometimes not in
a very logical place (for lack of a better one).  Unlike the FAQ, the
KB does not need to limit itself to issues that were raised several
times, it can store articles about the most subtle and rare occasions,
if we think they deserve that.

All the 3 documents should be extensively cross-linked and indexed,
to allow for easy use as a reference.