Hi Paul, I am starting to use DITA and really like it. But I can see your point regarding people being put off. It might be in a sense a bit too powerful for OFBiz and it takes a while to wrap your head around the concepts like maps, topics, etc ... I'm on the fence, maybe leaning slightly towards keeping DocBook, but if a PoC shows how DITA can shine, then why not!
Taher Alkhateeb ----- Original Message ----- From: "Paul Foxworthy" <p...@cohsoft.com.a Pau> To: dev@ofbiz.apache.org Sent: Saturday, 6 June, 2015 9:10:28 AM Subject: Re: Possible Documentation and help solutions - DITA Sharan-F wrote > I'm a bit unclear about what you are suggesting. > > * Is it about replacing the Docbook implementation we currently have > within OFBiz with something else (e.g Asciidoc)? > * Is it about extracting the Docbook content from what we currently > have in OFBiz and then generating it into another format that we > could possibly re-introduce? > * Or is it something else? Hi Sharan, My suggestion is much more modest than that. I think there's no need to replace existing DocBook content, or to totally change the DocBook process we have. All I am suggesting is that people consider AsciiDoc as a first step when authoring help information. If they prefer to work with DocBook directly, fine. There are tools to transform AsciDoc into DocBook XML, such as AsciiDoctor (http://asciidoctor.org/), so in effect (correctly written) AsciiDoc *is* DocBook. I'll repeat the reasons why I like AsciiDoc. It's more human-readable than XML. You can write your documentation in any text editor. Both of these are important. In contrast, requiring XML and some more specialised tool is a barrier to entry, so less people could and would participate in documenting OFBiz. When I last looked into DITA quite a few years ago, it seemed to be a heavyweight thing that only made sense if you wanted multiple destinations and were willing to invest in proprietary tools like Framemaker, Oxygen or Arbortext. I am perfectly willing to believe that DITA is more "complete" than DocBook, and would allow "better" documentation, if only anyone was willing to invest the time, trouble and money to be able to use it. I'm pleased to hear there's now DITA support for Eclipse. Eclipse is not my favourite IDE, but I could be persuaded to use it. How much better would it be to say to potential contributors that they can use their favourite IDE or text editor, whatever that is? If everybody else loves DITA, I would work with it. But I worry that it will put many people off. Thanks Paul Foxworthy ----- -- Coherent Software Australia Pty Ltd http://www.coherentsoftware.com.au/ Bonsai ERP, the all-inclusive ERP system http://www.bonsaierp.com.au/ -- View this message in context: http://ofbiz.135035.n4.nabble.com/Possible-Documentation-and-help-solutions-DITA-tp4669377p4669576.html Sent from the OFBiz - Dev mailing list archive at Nabble.com.