Hi Sharan, Well thought and makes sense. In a way our problem is in the process rather than the technology. And small steps are one of humanity's best concepts IMHO.
So may I suggest a set of actions to move forward: - First, we attempt to fix whatever is wrong in DocBook at the moment. If you can share exactly what you spotted then this would save us a lot of time in trying to dig to the problem. So a repeat process to identify the bugs from you would be great. - Second, we decide on a category structure for the sections of the documentation if we do not like the existing one - We also introduce or enforce a workflow that mandates an update of the documentation on each JIRA that affects functionality that requires documentation. For example, if we add or modify a screen in the party component, then we must provide the documentation for that screen before closing the JIRA for example. - As a last step we decide on the appropriate technology to move forward. Now, in the philosophy of small steps and being a guy who likes to jump into action, I suggest we start with the first point above and move from there. Thoughts? Taher Alkhateeb ----- Original Message ----- From: "Sharan-F" <sharan.f...@gmail.com> To: dev@ofbiz.apache.org Sent: Thursday, 4 June, 2015 11:01:58 AM Subject: Re: Possible Documentation and help solutions - DITA 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.