[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Doc organization (Re: Around again, and docs lead role)
From: |
Max Techter |
Subject: |
Re: Doc organization (Re: Around again, and docs lead role) |
Date: |
08 May 2003 23:12:54 +0200 |
User-agent: |
Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 |
Ricard Mira <address@hidden> writes:
> Max Techter wrote:
> > What about a tutorial, Ricard?
>
> There is already a Guile tutorial, but it's quite incomplete. On the
> other hand, it seems that most of the material in parts I, II and III
> of the Guile reference manual are introductory.
>
I agree on this.
But IMHO a tutorial and an introduction is
definitely not an exclusive alternative.
> I guess it's not clear yet whether Guile should have a separate
> tutorial, or an introductory section (or some introductory sections)
> in the reference manual.
>
Sure.
Anyway, keeping a tutorial separated
and on a different level(*)
is a good idea.
(Same principle as in python documentation).
(*) concerning what you suppose about the knowledge of
the audience, you are aiming at; concerning what you
want to communicate,...
If you keep the tutorial (which) should be
practical, the whirlwind tour should be theoretical.
Introductory stuff should be kept formal.
Tutorial may be informal, if necessary even
a little bit unprecise, but it has to get you going
immediately.
We should not bother too much about the structure
already there, if it is clear that there has to be
done some restructuring.
There are well known
principles how to document a system.
( And a standalone- (python),
or integrated-tutorial (bison) is a good ingredient for
the doc of every non trivial system) ;-)
The problem is not so much in finding a suitable
structure but in writing and maintaining, without
washing the structure away again.
Keeping the proportions is a problem too, but
we do not have to bother about this, now.
(
The work already done, is a fine prototype.
We may infer the structure needed, from the
problems this documentation posed.
).
Maybe I underestimate the complexity, of the needed
guile documentation.
I`ll try to work out a proposal.
I am engaged in scheme and guile anyway,
and this will force me to have a structured go.
(Guess I`ll need =< a fortnight)
regards
max.
- Re: Doc organization (Re: Around again, and docs lead role), (continued)
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Wolfgang Jaehrling, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), David Van Horn, 2003/05/09
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/10
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/15
- Re: Doc organization (Re: Around again, and docs lead role), Paul Jarc, 2003/05/15
Re: Doc organization (Re: Around again, and docs lead role), Max Techter, 2003/05/08
Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/08
Re: Doc organization (Re: Around again, and docs lead role), Max Techter, 2003/05/09
Re: Doc organization (Re: Around again, and docs lead role), tomas, 2003/05/09