<div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote">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 class="">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><div>I agree completely.<br></div><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><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">
My example of exquisite documentation produced by a documentation generator<br>
is the Trestle Reference Manual:<br>
<br>
<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><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></blockquote><div><br></div><div>Amazing.<br></div><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><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>