[gambit-list] Truck-Factor by mtov

Álvaro Castro-Castilla alvaro.castro.castilla at gmail.com
Fri Jul 24 13:14:47 EDT 2015


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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.iro.umontreal.ca/pipermail/gambit-list/attachments/20150724/52c39f5b/attachment.htm>


More information about the Gambit-list mailing list