[gambit-list] Truck-Factor by mtov

Hendrik Boom hendrik at topoi.pooq.com
Fri Jul 24 12:56:59 EDT 2015


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)?

Whatever is used, it should be something that can be compiled to an elegant 
document.

The documentation source code should be edited as plain ASCII or UTF-8 text
No trivial layout changes such as changing line boundarise to make it look 
pretty should be made in the source code -- this kind of thing, though it looks good, 
does not play well with revision control.

Markdown is popular for this. Asciidoc is possibly better because it is designed for 
making books rather than blog entries.  Scribble (from the Racket project) has the 
advantage of being Scheme-based, so it's possible to write Scheme programs to 
produce text where appropriate.

Note that Scribble-based documentation might fit well into Scheme source code, 
especially if there were some mechanism to filter it in or out of a partiular 
execution or compilation.

-- hendrik



More information about the Gambit-list mailing list