Cool stuff. I don't think we need something very structured and we are using markdown for the rest of the docs. I think it's important the docs are inside the code, but the usual reference structure makes them boring and inflexible.<div>
<br></div><div>I think<span></span> we should go ahead with docker.<br><br>On Wednesday, 15 May 2013, Manuel Quiñones  wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
2013/5/15 Manuel Quiñones <<a href="javascript:;" onclick="_e(event, 'cvml', 'manuq@laptop.org')">manuq@laptop.org</a>>:<br>
> 2013/5/14 Daniel Narvaez <<a href="javascript:;" onclick="_e(event, 'cvml', 'dwnarvaez@gmail.com')">dwnarvaez@gmail.com</a>>:<br>
>> Hello,<br>
>><br>
>> I think we should write a reference for the javascript API as we develop it.<br>
>> It's always hard to find time to do that after the fact and documenting it<br>
>> will help to come up with a better API.<br>
><br>
> Good point Daniel, I was going to suggest the same.<br>
><br>
>> Unless someone has alternatives to suggest (I have not spent much time<br>
>> investigating the topic), we should probably just use YUIdoc. It looks like<br>
>> a fine tool, it does what we need and it's based on nodejs like every other<br>
>> tool we are using.<br>
><br>
> I've been looking at literate programming [1][2] doc generators.  They<br>
> generate annotated source.  I've seen them used in a number of<br>
> javascript projects like Jasmine and CoffeeScript.<br>
><br>
> [1] <a href="http://jashkenas.github.io/docco/" target="_blank">http://jashkenas.github.io/docco/</a><br>
> [2] <a href="http://jbt.github.io/docker/src/docker.js.html" target="_blank">http://jbt.github.io/docker/src/docker.js.html</a><br>
><br>
> This is another approach to documentation than JSDoc and YUIdoc, and I<br>
> think it serves a slightly different purpose.<br>
><br>
> The literate programming docs:<br>
><br>
> - are useful for the developers too, can be an entry point for contributors<br>
> - don't need a very structured syntax with @tags, less work to do (and<br>
> we are still few)<br>
> - @tags that can be a bit redundant (marking a private member @private<br>
> for example)<br>
<br>
- Javadoc-like docs can be a pain to write without a specific IDE like Eclipse<br>
<br>
/me just remembered his bad experiences with Java :)<br>
<br>
--<br>
.. manuq ..<br>
</blockquote></div><br><br>-- <br>Daniel Narvaez<br><br>