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

[Neil Jerram <neil@ossau.uklinux.net>]

>>>>> "Max" == Max Techter <mtechter@gmx.de> 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 ....
     
    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?  How would you improve it?

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

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.

Thanks for your thoughts,

        Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel