[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Doc organization (Re: Around again, and docs lead role)
From: |
Neil Jerram |
Subject: |
Re: Doc organization (Re: Around again, and docs lead role) |
Date: |
08 May 2003 23:57:02 +0100 |
User-agent: |
Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 |
>>>>> "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 ....
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
- Re: Doc organization (Re: Around again, and docs lead role), (continued)
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), David Van Horn, 2003/05/09
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/10
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/15
- Re: Doc organization (Re: Around again, and docs lead role), Paul Jarc, 2003/05/15
Re: Doc organization (Re: Around again, and docs lead role), Max Techter, 2003/05/08
Re: Doc organization (Re: Around again, and docs lead role),
Neil Jerram <=
Re: Doc organization (Re: Around again, and docs lead role), Max Techter, 2003/05/09
Re: Doc organization (Re: Around again, and docs lead role), tomas, 2003/05/09