[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: |
27 May 2003 04:02:21 +0200 |
User-agent: |
Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 |
Max Techter <address@hidden> writes:
> Ricard Mira <address@hidden> writes:
>
> > Max Techter wrote:
> > > What about a tutorial, Ricard?
> >
> > There is already a Guile tutorial, but it's quite incomplete.
snip
[some arguments concerning tutorials snipped away]
> 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)
>
I have to correct myself here.
It should have been
(Guess I`ll need >= a fortnight)
Anyway, the work I promised to do is underway.
Although I will not propose a ready made lay out.
I`ll propose s.th. that is more like a process
for getting a documentation design.
What I did is s.th. like a documentation domain analysis.
This takes shape right now.
That is:
A Domain Dictionary has been initialized.
We need this for discussion.
And then
`The Guile Documentation Domain Dictionary'
may serve for feeding the Glossary in the end.
Use Cases are localized
(They answer the question
who, in which state, will consult which
part of the documentation to find what)
Some thought on dichotomies was spent:
policy-mechanism
concept-example
etc.
Important Documentation Patterns have been collected
introduction-main-conclusion
concept-example
subtypes are:
leading-example
subsequent-example
interleaved-example
tutorial
how to read this manual
site-map
elaboration
abstract
bold vision
history
etc
As soon as GNU documentation guide lines are reached
I`ll go public. I cannot go beyond this point
without your sayings!
Hopefully this procedure will naturally evolve
into a process which extends to part of the guile
community and specializes to Guile Documentation.
My understanding of documentation development has
been extended by doing these preparations.
So the work done so far was at least valuable for me.
Soon I call again, about those documentation issue ...
(The promised `commented manual' is underway too).
regards
max.
PS:
* Some people say I tend to over analyze, but I doubt the
thoroughness of their analysis ;-)
* The whole `Guile (based on Scheme) concept' leaves me
standing openmouthed, and I am wondering
a) how it could happen that nobody pushed me
into lisp/scheme before.
b) why the project has not been mentioned in work
dear to me
eg.
`Generative Programming' by Czarnecki and Eisenecker
or
Coplien`s `Multi-Paradigm Design', Thesis
(
Maybe I overestimate the guile potential,
but I constantly get this
"whoop, you can do this and then you could do
that" rush when working on scheme or guile.
Time will tell...
)
c) how it can be that some people, Stallman and others,
are thus farsighted (includes the elisp choice).
d) ...
- Re: Doc organization (Re: Around again, and docs lead role), (continued)
- 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