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