I am willing to work on a DITA PoC. Ron
On 04/06/2015 4:01 AM, Sharan-F wrote:
Hi Taher It would be good to understand what exactly is missing from our Docbook implementation. It might be that we have set the tags at a specific level (e.g section etc) which means that we cant use chapters etc. I'm still thinking but the main thing that concerns me is this. There is a lot of focus about changing the technology but no focus on how we integrate it or manage it. It's not only about changing the technology - we need to address the underlying problems. Why is our online documentation not being kept up to date? These are the main reasons I think are: - it is too hard to keep up to date as each change needs to be submitted as a patch - you need to understand and create the new data items for the CMS for each page of documentation - existing items need to be linked into the correct place in the document hierarchy - the docbook implementation isn't complete and there are a lot standard tags that cannot be used One the End User documentation side remember that Confluence is the Apache approved tools for wiki so we still need to work within this constraint for now. In any case – I think we firstly need to do some review of the all the documentation we have before we start structuring it. If changing to another format (DITA, Asciidoc etc) within OFBiz itself is going to generate a lot of work on the framework etc – why don't we try some small steps first just to see what we can do. It will also show if we can really start adding some value. Paul mentioned that Asciidoc could be a good compromise as it converts to Docbook and other formats. What about doing a small proof of concept (PoC) just to see what editing using Asciidoc could be like? The scope would be not to replace Docbook in OFBiz but just to see how we can use and edit in Asciidoc and how it can generate Docbook or other formats. - Could we extract the existing OFBiz online help and put it into Asciidoc format - Put the Online help Asciidoc somewhere where it can be edited and updated - Extract updated Asciidoc back into Docbook (or other) format - See if it can be re-introduced back into OFBiz (e.g. directly as a patch or as part as an ant target) Does this seem reasonable? If so are there any volunteers who'd like to work with me on this PoC? Thanks Sharan -- View this message in context: http://ofbiz.135035.n4.nabble.com/Possible-Documentation-and-help-solutions-DITA-tp4669377p4669411.html Sent from the OFBiz - Dev mailing list archive at Nabble.com.
-- Ron Wheeler President Artifact Software Inc email: rwhee...@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102