Re: Doc organization (Re: Around again, and docs lead role)

[Max Techter]

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.