Hello all I would like to welcome Christina Hough, who proposed her help for translating the Apache SIS developer guide from French to English. The developer guide is very incomplete - we basically had only the introduction chapters - but this could also be an opportunity to continue this work.
The developer guide was previously published on builds.apache.org. This is not possible anymore due to changes in the build system, and should probably be published on http://sis.apache.org/ instead. An open question before the work can start is which format to use? The current format is DocBook, but it can change if peoples think that we should. What I would like for the documentation format is: 1. Focus on the content rather than the appearance (i.e. any format that use styles, so we can said "this is a class name" rather than "this is a word in monospaced font"). 2. Support the writing of mathematical equations (e.g. MathML or anything equivalent). 3. Well suited for versionning on SubVersion or Git (i.e. not an opaque binary file), so we can get diff of reasonable size. 4. Reduce as much as possible the amount of format-specific details that a documentation writer must learn before he can contribute. Do peoples agree with those goals, or have anything to add? If the above goals seem okay, then: * The format could not be Wiki or "almost plain text" formats, since they do not comply to goals 1 and 2. * Word processing (Word, OpenOffice) does not fit very well with goal 3. Even if they can export in HTML format, they tend to add much more HTML tags than needed, or reformat the whole document, which make harder to inspect diff. * DocBook does not fit well with goal 4, since it forces the writer to learn a very specific format. I feel tempted to suggest to switch to a plain HTML 5 document, that we edit directly. HTML complies well with goals 1, 2 and 3. It mitigates the problem with goal 4, since there is much more peoples familiar with HTML than DocBook syntax, and anyone learning HTML for the aim of editing Apache SIS developer guide could leverage her learning in much wider range of contexts. Maybe there is also some good HTML editors (other than Microsoft Word) that are not too intrusive regarding HTML tags and reformating. One inconvenient of HTML is that we lost the automatically generated table of content, but we can write (or maybe found on the web) some scripts for doing that. What peoples thinks? Martin
