[gambit-list] Truck-Factor by mtov

Adam adam.mlmb at gmail.com
Fri Jul 24 15:01:36 EDT 2015


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 at gmail.com>:

>
> On Fri, Jul 24, 2015 at 6:46 PM, Hendrik Boom <hendrik at 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 at iro.umontreal.ca
> https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.iro.umontreal.ca/pipermail/gambit-list/attachments/20150724/5c58e046/attachment.htm>


More information about the Gambit-list mailing list