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 >
