Yeah I really like asciidoc too. I'm making a comparison below specific to our community for making a choice. Please feel free to correct it or complete it, it's just a quick idea dump.
DocBook pros: - Mature, many books available to read - Excellent documentation - Already exists in OFBiz - Tools and utilities are numerous DocBook cons: - Not modular, more suited for books and articles - Verbose XML - Very complex vocabulary with hundreds of tags and countless combinations AsciiDoc pros: - Human friendly - Minimal learning curve for new users - Despite simple syntax it has powerful publishing capabilities - Good documentation AsciiDoc cons: - No books (AFAIK) and online troubleshooting is minimal - Not modular similar to DocBook - Tooling support is lacking and few editors support it like vim, emacs, gedit. Dita pros: - Mature and many books available to read - Most utilized standard for content authoring and deployed in many large contexts - Good documentation (I think DocBook is much better though) - Modular: this is the single most powerful feature. It allows reusing content and even parameterized content. The same piece of content could be used in a tutorial, online help and reference documentation for example. - Good tooling support (dita-ot) but again nothing beats DocBook in that area. Dita cons - Verbose XML syntax - Steeper learning curve due to vocabulary (but nothing compared to DocBook) - Not very well suited for long documentation (not sure if we have it / need it) I hope I got things right. I think all solutions above are good and I lean slightly towards dita because of the modularity aspect. Taher Alkhateeb On Aug 21, 2016 9:03 AM, "Jacques Le Roux" <[email protected]> wrote: > Le 20/08/2016 à 21:15, Jacques Le Roux a écrit : > >> - Provide full documentation through a powerful publishing solution such >>> as >>> DocBook or DITA. >>> >> >> +1, but we need to have a consensus with the tool, Paul and I advocated >> for instance >> > Err, forgot "AsciiDoc" in this sentence :/ > Note: there are AsciiDoc plugins for Eclipse and IntelliJ. With Pandoc you > can transform almost all formats to another > > Interesting contradictory PoV on DITA http://idratherbewriting.com/2 > 015/01/28/10-reasons-for-moving-away-from-dita/ > > Jacques > >
