Hi, OpenOffice could be an option but have the same problem as Word:
1. personal taste: same issue as Word, I don't like triggering a big tool just to fix few typos for instance. 2. consistent output: many people (I hope...) will enrich this document. How to make sure we'll have the same consistent output with tools like OO or Word ? Correctly use styles ? Will this be enough ? Will we be able to keep a professional (or high quality) looking documentation ? 3. important point is to be able to put in under SVN so we can see differences between two versions, what's been added in the local copy, ... just like code. Word as OO docs are imported as binary format, and SVN won't show any diff on it (just an "something has changed..."). How to make sure someone didn't change something unexpectidely ? 4. how to (easily) script documentation processing ? When original doc source is in format like LaTEX, Docbook or ASCIIDOC, you can make it built, checked and produce output automatically. Cheers, Seb > > I don't understand why not OpenOffice.org doc? It can export also in > HTML/XHTML, PDF, MediaWiki txt, BibTeX, LaTeX 2e and is ported on all > operating systems. It can save also in MS Word format, and many > others. > > ------------------ > Vasi (http://moriscanet.blogspot.com) > > On Aug 21, 3:52 pm, Sebastien Lelong <[email protected]> > wrote: > > 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 Lelonghttp://www.sirloon.nethttp://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 -~----------~----~----~----~------~----~------~--~---
