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

[Max Techter]

Mikael Djurfeldt <address@hidden> writes:

> Bill Schottstaedt <address@hidden> writes:
> 
> > My take on Guile (which seems to me to have stalled out over the last
> > few years) is that the current developers think of it as an extended
> > shell-based interpreter
> 
> Maybe this is totally out of context and misplaced---
snip 

        I don`t think so, Mikael. 

        Part of this thread stayed on documentation issues.

 
        I promised, to use my current first dive 
        into scheme and guile to produce 

        * critical remarks on the documentation 

        * a proposal for changes concerning the
          overall-layout of the documentation

        
        As I got it, 
        Neil thinks that "high level questions" about 
        documentation structure have to be dealt with. 

        
        Your mentioning of once formulated goals 
        for the guile project fits quite well. 


        
> I include below the stated goals of Guile.  Even though I'm not a
> particularly active developer right now, these are goals that I
> support strongly, and I think most of the other developers do as well,
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
snip 


        If this is the case, the introductory parts of the
        manual should directly reflect these goals, as you
        state below.
        (I would say the guile tutorial should do so too) 

        This would have accelerated my efforts to grasp the 
        guile concept and scope quite a bit. 
       
        
> My contribution to this discussion would be that there is no single
> "canonical" way of using Guile.  Rather, there is a small handful of
> canonical ways (which are reflected in the goals below).  
snip 


> I therefore think that many of the ideas that were discussed before
> initiating work on the current manual were very good: that the manual
> should present Guile from a small set of viewpoints connected to the
> small set of canonical ways to use Guile.
snip 


        I cut out your thoughts on the C API, 
        because I have no opinion on this issue yet.


> workbook/policy/goals.text
> ----------------------------------------------------------------------
> This file states the goals of Guile.
> 
> * Goals of Guile
> 

> ** Guile as an extension language library
> 

> ** Guile as a programming language
> 

> ** Guile as an interface to the operating system
> 

> ** Guile as an interactive shell
> 

> ** Guile as an integration platform
> 

> ** Guile as a basis for other languages
> 


        As a newbie I agree with Mikael's reasoning and
        conclusions.
        
        What goes against using this structure for the
        introduction part of the manual?
        
        Then --if possible-- reflecting it in the tutorial
        and maybe it could even be used as a pattern for
        subsequent parts of the manual.  I am not sure about
        this, but I bet most of the existing (and valuable)
        stuff of the documentation could be fitted in such a
        layout.

        It would be a structure a guile newbie could hang on
        to (I miss such a lifeline in the current manual),
        when coping with all those "strange new scheme and
        guile" concepts at once.


        
regards max.

PS:
        We would have to change the order: 
        
                programming language 
                        and 
                interactive interpreter 
        
        comes first, then 

                interface to os

        then the 
        
                advanced concepts: 
                        extension, integration, ...
                (already mentioned --in short-- at the top of cause)