Re "how to document Gambit's inner workings":

I guess the videoconference is the first real more complete understanding - this time into the IO subsystem - that the community gets.

Informal documents or writeups, even just dropped as email here on the ML, will go a long way.

(The totality of documentation right now is pretty much http://dynamo.iro.umontreal.ca/wiki/index.php/Internal_Documentation , so every line of documentation published on the ML will be a milestone :) )


2015-07-24 19:14 GMT+02:00 Álvaro Castro-Castilla <alvaro.castro.castilla@gmail.com>:

On Fri, Jul 24, 2015 at 6:46 PM, Hendrik Boom <hendrik@topoi.pooq.com> wrote:
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
>
> What would have the most impact - commenting inside the source code, or external
> documentation (perhaps a wiki), or something hybrid, like encoded comments inside
> the source code that could be "compiled" to viewable comments, similar to, for
> example, Javadocs)?

I've  found most automatically generated documentation to be nearly worthless.

That said, I think that documentation should be located together with the code it
documents, and extracted with an automatic documentation engine.

The point is that the documentation still needs to be written.   By people who care
that the final product is readable, clear, and pricise.  But it needs also to be
close to the code, so that it can be updated when its code is updated.



I agree completely.


 
There also have to be introductory sections that tie everything together.  These
sections  often do not belong with any source-code component of the source
code.  They are essential for someone approaching the system for the first time.


High-level view of the project is as important as the low-level documentation of the specific techniques used.

 
My example of exquisite documentation produced by a documentation generator
is the Trestle Reference Manual:

http://www.std.org/~msm/common/SRC-RR-068.pdf

If you look at the source code for Trestle, you'll find the source code
for the manual there, ofter interspersed in the interface files.
I'm sure that getting it to be coherent when extracted and displayed took significant
effort in the design of the documentation generator and in the source code of the
documented modules.


Amazing.

 
The immediate practical question in this approach is:

How can we organise a crowd-sourced effort to accomplish this?
A wiki is the usual answer, but it fails in terms of integration with the source
code, which is essential to keeping it up-to-date with code changes.


I think the best way would be to use the pull-request/review approach on github. It's a common way of doing it, and it works well for making sure of consistency. Contributors fork and add changes to documentation in a branch, then open pull request. This PR will be reviewed and merged by Marc and other "core" contributors of Gambit, as in many opensource projects.

Key to this would be that a general structure is first laid in place.

This can be implemented with Scribble, markdown or anything in those lines.
 

_______________________________________________
Gambit-list mailing list
Gambit-list@iro.umontreal.ca
https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list