<div dir="ltr">Re "how to document Gambit's inner workings":<div><br></div><div>I guess the videoconference is the first real more complete understanding - this time into the IO subsystem - that the community gets.</div><div><br></div><div>Informal documents or writeups, even just dropped as email here on the ML, will go a long way.</div><div><br></div><div>(The totality of documentation right now is pretty much <a href="http://dynamo.iro.umontreal.ca/wiki/index.php/Internal_Documentation">http://dynamo.iro.umontreal.ca/wiki/index.php/Internal_Documentation</a> , so every line of documentation published on the ML will be a milestone :) )</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">2015-07-24 19:14 GMT+02:00 Álvaro Castro-Castilla <span dir="ltr"><<a href="mailto:alvaro.castro.castilla@gmail.com" target="_blank">alvaro.castro.castilla@gmail.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote"><span class="">On Fri, Jul 24, 2015 at 6:46 PM, Hendrik Boom <span dir="ltr"><<a href="mailto:hendrik@topoi.pooq.com" target="_blank">hendrik@topoi.pooq.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span>On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:<br>
><br>
> What would have the most impact - commenting inside the source code, or external<br>
> documentation (perhaps a wiki), or something hybrid, like encoded comments inside<br>
> the source code that could be "compiled" to viewable comments, similar to, for<br>
> example, Javadocs)?<br>
<br>
</span>I've  found most automatically generated documentation to be nearly worthless.<br>
<br>
That said, I think that documentation should be located together with the code it<br>
documents, and extracted with an automatic documentation engine.<br>
<br>
The point is that the documentation still needs to be written.   By people who care<br>
that the final product is readable, clear, and pricise.  But it needs also to be<br>
close to the code, so that it can be updated when its code is updated.<br>
<br></blockquote><div><br><br></div></span><div>I agree completely.<br></div><span class=""><div><br><br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
There also have to be introductory sections that tie everything together.  These<br>
sections  often do not belong with any source-code component of the source<br>
code.  They are essential for someone approaching the system for the first time.<br>
<br></blockquote><div><br></div></span><div>High-level view of the project is as important as the low-level documentation of the specific techniques used.<br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
My example of exquisite documentation produced by a documentation generator<br>
is the Trestle Reference Manual:<br>
<br>
</span><a href="http://www.std.org/~msm/common/SRC-RR-068.pdf" rel="noreferrer" target="_blank">http://www.std.org/~msm/common/SRC-RR-068.pdf</a><span class=""><br>
<br>
If you look at the source code for Trestle, you'll find the source code<br>
for the manual there, ofter interspersed in the interface files.<br>
I'm sure that getting it to be coherent when extracted and displayed took significant<br>
effort in the design of the documentation generator and in the source code of the<br>
documented modules.<br>
<br></span></blockquote><div><br></div><div>Amazing.<br></div><span class=""><div><br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The immediate practical question in this approach is:<br>
<br>
How can we organise a crowd-sourced effort to accomplish this?<br>
A wiki is the usual answer, but it fails in terms of integration with the source<br>
code, which is essential to keeping it up-to-date with code changes.<br></blockquote><div><br><br></div></span><div>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.<br><br></div><div>Key to this would be that a general structure is first laid in place.<br><br></div><div>This can be implemented with Scribble, markdown or anything in those lines.<br></div><div> </div></div></div></div>
<br>_______________________________________________<br>
Gambit-list mailing list<br>
<a href="mailto:Gambit-list@iro.umontreal.ca">Gambit-list@iro.umontreal.ca</a><br>
<a href="https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list" rel="noreferrer" target="_blank">https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list</a><br>
<br></blockquote></div><br></div>