Date: Wed, 10 Jan 2001 19:56:18 +0200
From: "Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
Sender: halo1 AT zahav DOT net DOT il
To: JT Williams <jeffw AT darwin DOT sfbr DOT org>
Message-Id: <7263-Wed10Jan2001195617+0200-eliz@is.elta.co.il>
X-Mailer: Emacs 20.6 (via feedmail 8.3.emacs20_6 I) and Blat ver 1.8.6
CC: djgpp-workers AT delorie DOT com
In-reply-to: <20010110083821.B24622@kendall.sfbr.org> (message from JT
	Williams on Wed, 10 Jan 2001 08:38:21 -0600)
Subject: Re: Start to section for KB on how to contribute to DJGPP
References: <3A4BA452 DOT BB6ADC3F AT bigfoot DOT com> <3A4CB0B3 DOT 9ADC93C AT softhome DOT net> <4331-Sun31Dec2000122524+0200-eliz AT is DOT elta DOT co DOT il> <20010110083821 DOT B24622 AT kendall DOT sfbr DOT org>
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: Wed, 10 Jan 2001 08:38:21 -0600
> From: JT Williams <jeffw AT darwin DOT sfbr DOT org>
> 
> -: Large parts of the FAQ should actually be converted into the Knowledge
> -: Base sections.  Feel free...
> 
> Could you elaborate?  For example, what are some sections of the FAQ
> that you feel should be transferred to the KB?

If you look at the FAQ closely, you will see that many sections are
not really answers to a small number of similar questions, but a
hodgepodge of snippets of information about related problems and their
solutions.  Each one of these snippets should be converted to a
Knowledge Base article.

In addition, there are specific HOWTOs in the FAQ, like the section
about turning off numeric tails on Windows, which also belong to the
Knowledge Base.

The FAQ should ideally include only a small number of answers to
_really_ frequently-asked questions, with all the rest moved either to
the Knowledge Base or the User's Guide.

> The current djgpp documentation is substantial, but IMHO it needs some
> `organization'.  We have a fabulous FAQ, a Knowledge Base, a User's Guide,
> various HowTo's and ReadMe's, tutorials, and so on.  We have a massive
> mail archive that contains lots of useful information.  By and large,
> it's all there, but fragmented and scattered.  Is there a long-term goal
> (or wish) for integrating all this documentation?

Goals do exist, but IMHO they are by and large irrelevant without
motivated individuals who actively work on this.

> What is a `Knowledge Base', and how should it differ from a `User's Guide'
> or from a hypothetical `DJGPP book'?  What are the reasons for having
> both the KB and the UG?  Would it be preferable to pull most everything
> together into a sort of "Hitchhiker's Guide to DJGPP"?

User's Guide should IMHO contain a tutorial introduction to setting up
and using DJGPP, and a few chapters about more advanced issues, like
porting Unix software, creating a development environment, etc.  By
contrast, the Knowledge Base is a heap of short recipes for solving
specific problems, which is not intended to be read in its entirety,
but searched for keywords.  HOWTOs can be made part of the Knowledge
Base as well, I guess.

> If someone were to donate effort to `djgpp documentation project',
> how would that effort best be spent?

I'd begin by making the libc docs better.  For example, libc.info is
in dire need of a good index, so that users could easily find what
function they need e.g. for creating a directory; global variables and
environment variables mentioned in libc.info also need to be indexed.

Another important missing piece is the User's Guide.  It should be
assembled from README.1ST, a few sections from the FAQ (such as
chapters 1 and 2, sections 4.1 and 4.2, etc.).

The other major job is the documentation of the library internals.
This should include, in addition to the important aspects of the
internal library operation per se, also the descriptions of the DPMI
setup done by the startup code, of exception and signal handling, and
of the debug support.

I think this is enough work for about 10 man-years, so I'll stop here ;-)