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

[Max Techter]

Neil Jerram <address@hidden> writes:

> >>>>> "Ricard" == Ricard Mira <address@hidden> writes:
> 
> 
>     Ricard> As a user who is learning Scheme to customize and extend
>     Ricard> Guile-using programs, I expect the Guile documentation to
>     Ricard> contain a section for each programming language (C and
>     Ricard> Scheme for sure; translated languages maybe).  Then I need
                                                             ^^^^^^^^^^^
>     Ricard> to read just the Scheme section (and maybe also a general
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>     Ricard> introduction).
      ^^^^^^^^^^^^^^^^^^^^^

snip 

      What about a tutorial, Ricard?

Hi, 

I am new to guile, 
my name is max.


I came across guile, when I gathered information about: 

        What makes up a GNU Package.

As I got it: 

        The decision was and is: 

        The GNU Glue, should be GUILE.
        
Being interested in providing my own stuff to the GNU
Project and/or in giving help to another GNU Package, 
I accepted the need to dive into GUILE. 


Thus I naturally had an eye on this thread 
about the need of restructuring and improving the
documentation. 


> 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.)

     My first impression was: 
        Oops...
        such an important project, but obviously
        abandoned...

     The documentation is one of the first important 
     impressions a (potential) user gets. 

     
     I typically look out for a tutorial, immediately 
     after installation. Not to learn, but to find out:
     
        is this something for me? 

      
> 
> Specifically, I think we should (**) promote doing as much programming
> as possible in Scheme, 

      Yeah. 

> and restrict documentation of the C API to the
> parts needed for interfacing Scheme to C code.  
snip 

      Yeah.

> , I think the natural high level documentation structure
> would then be:
> 

     I am missing, things like: 

        * Tutorial 
              
               
        * Introduction 

                ** Background, History 
                ** Advantages 
                ... 

        Basic Concepts, or whatever 

        * Rational / Advocacy

                ** nothing you can`t do with lisp like
                   languages, 

                ** hackable, short path to C  
                
                ** scientific background 
        

        * GOOPS 
                
                (proof of the `nothing you can`t do
                statement) 
               

        * R5RS 

        * Other freely available or even included documentation 

               


     (Some of these sections need not be high volume
     but they serve important purposes.) 


     
> - 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:

        Task based structuring the meat of the documentation
        is an idea I like, Neil.
        
        That`s what we use software for: 
                Solving Tasks 
                (beside for having incredible fun, of cause =:)


>   - writing and exporting primitives (in modules)

>   - smobs, GC, lifetimes etc.

>   - Guile initialization from within a library

>   - how to call out to a Scheme-defined procedure

>   - how to look up a Scheme-defined variable

>   - how to evaluate user-supplied code and catch errors

>   - (anything else that I've missed).

> Which has something in common with your thoughts.
> 
> That's what I'm thinking now, anyway.  I think (**) may be quite
> controversial, 
> so that at least needs a lot more discussion first.

        Here we are...

regards 
max.