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

[Max Techter]

Neil Jerram <address@hidden> writes:

> >>>>> "Max" == Max Techter <address@hidden> writes:
> 
>     >> My latest thinking is that we could be a lot more concrete, even
>     >> proscriptive, about what Guile is for and how people should use it,
>     >> and that if we did so it would be a lot easier to clearly assess the
>     >> state of the documentation and to finish it off.  
> 
>     >> (Right now, IMO, it is difficult even to describe the
>     >> documentation status.)
> 
>     Max>      My first impression was: 
>     Max>         Oops...
>     Max>         such an important project, but obviously
>     Max>         abandoned...
> 
> I don't see how you can conclude that the project is abandoned when
> we're right in the middle of a thread about it ....
>      

        I installed the guile package, had a look 
        at the manual and at  the tutorial before 
        I subscribed and read the mailing list.


>     Max>      I typically look out for a tutorial, immediately 
>     Max>      after installation. Not to learn, but to find out:
>      
>     Max>         is this something for me? 
> 
> Did you look at the Guile Tutorial?  

        Yes, I did. 

        That`s what I do as one of my first steps, 
        when exploring s.th. new to me.

        And this was part of the things 
        that caused my _first_ and _wrong_ impression.

                Oops, abandoned. 
        
        Important GNU Packages, have excellent doc,
        guile doc is not bad, but not excellent either.

        (although it is an important Package, 
        as I got it now, and not abandoned...      :-)


> How would you improve it?
> 

        Too much to say about this, 
        to be appropriate for this reply.

        I`ll tell you in a couple of days, more precisely. 

        So far only this:

        As an example: 
        There is a section 

                Using recursion to process a list.

        Before anything was said about pairs, 
        and lists, and the concept of the null
        in scheme. 

        If this is an tutorial about scheme, you can`t 
        ask the (potential) user, to take such a leap.
        You can do this in a preview, but not in 
        a tutorial.
        
        Now if this is not a scheme tutorial, 
        (the Title says `Guile tutorial'),
        there is no need to supply such an 
        example, because it is a standard 
        scheme construct.

        The problem is: 
            the parts of the documentation 
            seen as isolated pieces of 
            knowledge, are good, though not complete.

            But being new to guile, and to scheme 
            I had problems to grasp the context (and the
            rational).
 

>     >> , I think the natural high level documentation structure
>     >> would then be:
>     >> 
> 
>     Max>      I am missing, things like: [...]
> 
> I agree, and some of these pieces are already in place - see the Guile
> Reference manual.  But I was really focussing on the issue of Scheme
> and C API documentation in my last message.
>      
        Ok, obviously I missed your focus.

        That is because I am still struggling to get the big
        picture:



        The Algorithmic Language Scheme

        * GOOPS: (goops).               The GOOPS reference manual.
        * Guile Reference: (guile).     The Guile reference manual.
        * Guile Tutorial: (guile-tut).  The Guile tutorial.
        * R5RS: (r5rs).                 The Revised(5) Report on Scheme.

        (slib is missing in my local installation, what else
        is missing?) 
         
                
>     >> - Scheme reference documentation - more or less like the current Part
>     >> IV, but Scheme only, not C.
> 
>     >> - Task-based documentation describing everything needed for aspects of
>     >> interfacing with C code:
> 
>     Max>         Task based structuring the meat of the documentation
>     Max>         is an idea I like, Neil.
>         
>     Max>         That`s what we use software for: 
>     Max>                 Solving Tasks 
>     Max>                 (beside for having incredible fun, of cause =:)
> 
> OK, but given a general purpose language like Scheme, there's a limit
> to how fully you can document it in a task-based way.  


> For Scheme you
> need a combination of reference documentation and examples.
> 
                
       I agree. 

       It is clear that this task-based way has advantages 
       and  has tight limits on the other hand.

       And may I add: 

       Reference 
        
              with short examples.

       Tutorial 

               with intermediate examples, 

       Introduction / Basic Concepts 
                by the way, IMHO there should be a section 

                * `Basic  Concepts of Scheme' 
                      as there already is 

                __and__

                * `Basic  Concepts of Guile' 
                      maybe the Whirlwind tour could be 
                      extended to such a section, and
                      later on this extension could be boiled
                      down again to an improved Whirlwind tour
        
       
               both with longer examples
                (like the one in `An Example of Non-Lexical Scoping'
                 which helped me quite a lot, to dig  one 
                 of the not so simple concepts.) 
       

> The C API on the other hand - at least as I think we should see it -
> is not general purpose.  

> It has the specific job of interfacing C to
> Scheme and so can be fully covered in a task-based way.
> 
     I am definitely not the one to comment on this, 
        not yet   ;-)

regards 
max.


PS: 
    I would like to help in formulating the overall layout,
    and I am prepared to get my hands on real work,
    concerning the tutorials, if it is decided on 
    having (or keeping) them.