Re: Around again, and docs lead role

[Max Techter]

Neil Jerram <address@hidden> writes:

snip
> 
> That said... is there anyone out there who'd be interested in taking
> over the lead role on Guile documentation?
> 
> I have three reasons for asking this:
> 
> - I don't expect to have a _lot_ of time for Guile soon, and the docs
>   would benefit from someone with more time available.
> 
> - I have other Guile interests that I'd like to spend some of that
>   time on.
> 
> - A new pair of eyes could take a fresh look at the higher-level doc
>   issues such as overall organization, what kind of docs we need
>   (e.g. the cookbook idea) etc.
> 
> Any takers?
> 
        
Hi, 

I am new to guile, new to this list 

(though I posted a couple of replies concerning the overall
structure, and the principle need of tutorials)

I am not ready to offer to take the lead role on Guile
documentation, but I offer to `throw in my two cent' as
Thamer put it in a subsequent posting in this thread.


Last weekend I managed to spare an evening for diving deeper
into the

        `Guile Reference Manual',  
        Edition 1.0, for use with Guile 1.6.2 

The first impression I had was verified:

        A prototype of a documentation. 

        Lacking an understandable high level structure.

        Inconsistent in things that should be common 
          (Eg. sometimes the aim and the audience of the section
           is mentioned, sometimes not) 

        Inconsistent in things that should vary 
          (Eg. different sections, chapters, parts freely
          mix the level of the examples supplied) 
        



Right now I am adding up pall pen remarks to my printed
version, these would normally go down the shredder, after I
managed to extract my private documentation map.


If you think, that in the current state of discussion, this
kind of critique could be useful, tell me:

        hacking revised comments into, say  the .texi
        source, would not put a too heavy workload on me.

regards 
max.