Hi guys,
You've probably heard about documentation issues these last weeks. Toon and Joep started to write a "jalv2 & jallib - an introduction" document. As a Word file. First drafts clearly show interests for this kind of documentation, but there are lots of other source of information which could be used to enrich it, like some blog posts. Maybe it's time to normalize this and provide a common way to produce this kind of documentation. One important aspect is it must be under SVN. Not only the file, but also the content. SVN should be able to deal with documentation as it does for the code, namely documentation should be in text format. It also shouldn't a pain fixing just a typo, so not having a turn on Word would really make things easier (IMO). Finally, one source (one file) must be able to produce different format, like HTML, PDF, ASCII, PS or the like. And this whole thing must be scripted, so it's part of the development process (hopefully as a quality requirement). So... this raises the question: "which tool ?". Professional documentation writer, if any here, may help. I'm not a doc write, but used LaTEX, Docbook and ReST a litlle. Recently, I had a look at Asciidoc, and it seems quite a nice choice (http://www.methods.co.nz/asciidoc/). It allows to have a readable ASCII doc, and produce very nice HTML, XHTML, PDf, etc, ... and intermediary format like Docbook. Highly configurable too. Ideally one would write his doc in his format, integrate it to the main book ("an introduction") but also upload it to our upcoming jalv2 website. I think I'll try to convert current Toon&Joep's document and let you have a look at the results. In the meantime, if you have suggestions and/or objections... (and most importantly, will you agree to invest some time on this kind of tool ?) Cheers, Seb -- Sébastien Lelong http://www.sirloon.net http://sirbot.org --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "jallib" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/jallib?hl=en -~----------~----~----~----~------~----~------~--~---
