Re: Around again, and docs lead role

[Neil Jerram]

>>>>> "Ricard" == Ricard Mira <address@hidden> writes:

    Ricard> Neil Jerram wrote:
    >> Thanks Ricard; please see also my reply to Thamer.  What are your
    >> views so far about the existing docs?  (I'm finishing for
    >> a cold hard assessment here, not compliments.)

    Ricard> IMHO, the overall organization of the documentation isn't
    Ricard> clear.  But I know that documenting Guile is difficult,
    Ricard> because there are many different things to consider (C and
    Ricard> Scheme, Scheme and translated languages, applications and
    Ricard> Guile, etc.).

Indeed.  This also makes it difficult to assess the overall status of
the docs, and in particular how close we are to being "finished".

    Ricard> I am thinking about these issues.

That's great.  I've been thinking about these over the last couple of
days as well, but I'll save my half-formed thoughts for the moment so
as not to prejudice yours.

    Ricard> Also, I believe that "Part V: Guile Modules" should
    Ricard> disappear, because features should be documented according
    Ricard> to their functionality, not according to their origin or
    Ricard> implementation (SLIB, SRFIs, etc.).

Possibly yes.  I think it might be useful to keep a dividing line
between core Guile and available add-ons (e.g. SLIB and JACAL), but it
may well be that the dividing line we have now is not in the right
place.  Bear in mind that in some mythical future there will be lots
of Guile-using applications - already there are e.g. Gnucash,
Lilypond, TeXmacs - that might provide useful library functions.  I
think it will be desirable at least to include pointers in the Guile
manual to those applications' documentation, so we need somewhere to
put those pointers.

Best regards,
        Neil