Thanks Taher. AsciiDoc is designed to translate to Docbook, so all the Docbook ecosystem can be used with AsciiDoc. You can think of AsciiDoc as an alternative syntax to Docbook XML that is more accessible as you write. It feels like you're writing an email.
So to my mind our choice is between two options: DITA or AsciiDoc/Docbook. AsciiDoc is just as modular as Docbook. AsciiDoc does need a specialized tool, AsciiDoctor, to create Docbook, but I don't think that's a big problem. Cheers Paul Foxworthy On 8 June 2017 at 18:54, Taher Alkhateeb <slidingfilame...@gmail.com> wrote: > Reading through the threads provided by Paul reminded me of the reason why > we suffered in making a decision. Documentation is very important, and very > boring! > > I think we all agree now (more-or-less) that documentation inside the code > base is probably better. The question to raise (again!) is which technology > to use. > > So how to choose? I list some criteria we might consider: > > - Simplicity: The easier it is to learn this technology, the more people > will be able to contribute. > - Modularity: The more modular the documentation system the better so that > we minimize copy-and-paste patterns. > - Migration Ease: The easier it is to migrate existing work the better > (e.g. keeping the same technology or having conversion scripts) > - Verbosity: The less verbose the documentation syntax the better > - Automation: The easier it is to automate the documentation generation the > better. Ideally it should work directly from the build system (Gradle). > - Ecosystem: The more resources, books, tools, support, editors and IDEs > for the documentation system the better. > > I'll try to summarize earlier discussion points along with some of my own: > > - The candidates we discussed are AsciiDoc, DocBook and DITA. > - DocBook is the existing implementation but it is broken as it only > implements a subset of the full standard. So we have to fix or replace. > - AsciiDoc is probably the simplest of the three and DITA is probably the > most complex > - DITA is the most modular and AsciiDoc is the least modular > - DITA and AsciiDoc require specialized tools whereas DocBook can just work > with good old XSLT > - DITA and DocBook are too verbose, AsciiDoc has a lighter and nicer syntax > - I could be wrong about the eco-system, but I think the biggest is DocBook > followed by DITA and then AsciiDoc. > > I hope these points can help to better focus the discussion. > > Cheers, > > Taher Alkahteeb > > On Thu, Jun 8, 2017 at 10:54 AM, Paul Foxworthy <p...@cohsoft.com.au> > wrote: > > > Hi all, > > > > A reminder AsciiDoc came up in discussions in 2015: > > > > http://ofbiz.135035.n4.nabble.com/Some-comments-on-DITA-for- > > a-small-group-td4670183.html > > http://ofbiz.135035.n4.nabble.com/Possible-Documentation- > > and-help-solutions-DITA-td4669377.html > > > > Cheers > > > > Paul Foxworthy > > > > > > On 8 June 2017 at 17:22, Sharan Foga <sharan.f...@gmail.com> wrote: > > > > > Hi Zoran > > > > > > Thanks very much for the response. I'll take your feedback back to the > > > OFBiz community as you have highlighted some interesting ideas that > could > > > be very useful for us. > > > > > > Thanks > > > Sharan > > > > > > > > > On 2017-06-06 16:12 (+0200), Zoran Regvart <zo...@regvart.com> wrote: > > > > Hi Sharan, > > > > we use a CI job that runs a custom built tool to export Confluence > > > > pages into HTML[1], but that being said we are in the process of > > > > moving the wiki content into the source tree and generating/updating > > > > the documentation as a part of the build process. For that we use a > > > > custom Maven plugin[2] and asciidoctor for makup. > > > > > > > > In somewhat near future we'll replace the wiki export with a static > > > > site generator like Jekyll or Hugo. > > > > > > > > We hope that having the documentation along with the source code will > > > > keep it more up to date and encourage more contribution to the > > > > documentation, > > > > > > > > zoran > > > > > > > > [1] https://svn.apache.org/viewvc/camel/website/ > > > > [2] https://github.com/apache/camel/tree/master/tooling/maven/ > > > camel-maven-plugin > > > > > > > > On Mon, Jun 5, 2017 at 1:30 PM, Sharan Foga <sha...@apache.org> > wrote: > > > > > Hello Apache Camel Community! > > > > > > > > > > I'm from the Apache OFBiz community and we are in the process of > > > re-designing our website and doing some significant tidying up and > > > restructure of our confluence workspaces and wiki. > > > > > > > > > > Someone highlighted that your project website and wiki look great, > > > well organised and integrated so please could I find out some > information > > > from you about what you've used and how you've done it. :-) > > > > > > > > > > Thanks > > > > > Sharan > > > > > > > > > > > > > > > > > > > > > -- > > > > Zoran Regvart > > > > > > > > > > > > > > > -- > > Coherent Software Australia Pty Ltd > > PO Box 2773 > > Cheltenham Vic 3192 > > Australia > > > > Phone: +61 3 9585 6788 > > Web: http://www.coherentsoftware.com.au/ > > Email: i...@coherentsoftware.com.au > > > -- Coherent Software Australia Pty Ltd PO Box 2773 Cheltenham Vic 3192 Australia Phone: +61 3 9585 6788 Web: http://www.coherentsoftware.com.au/ Email: i...@coherentsoftware.com.au
