Hey Martin, Thanks for introducing Christina! I think that it might make the most sense to publish the content directly on to the website as HTML5 as you suggested. Christina can write the translated content out as plain text and we can port it over for her. Does that sound reasonable?
Adam On Thu, Jul 31, 2014 at 5:59 AM, Martin Desruisseaux <[email protected]> wrote: > 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 >
