Hi All I think the issue we have with documentation is a complex one and I don't think that all the different types of documentation that we need for OFBiz could all reside within the codebase at this stage. Perhaps in the future, though it depends on how our existing documentation effort evolves.
See link the the email I sent a couple of weeks ago about how we are planning to work on structuring our documentation effort. https://s.apache.org/tmMX We are working on multiple documentation channels and need to focus on writing, reviewing and generating the content because without the content â we won't have anything and currently Confluence can fulfill most of these channels. At this stage for me this discussion is primarily concerned with implementing something that will manage our End User Menu Structured Documentation within the OFBiz applications. This is something we can't effectively do (or would want to do in ) Confluence. We already have content available to update some of this but it has been on hold pending this discussion and decision on the technology. At the moment within OFBiz, we have some limited screen and application help which I think we need to keep and improve. This is help that appears when someone is on a screen or within an application, and they they can click the help button. In the past we have had 2 contributor efforts to correct our docbook implementation to use the Webhelp. One effort was done a separate branch and the original contributor Tom Burns died suddenly so it was never merged. As a tribute to Tom, I understand that Olivier Heintz picked up Tom's work and converted into an OFBiz add on for 13.07. I've seen the Webhelp addon working for 13.07 and it works well and also looks good, so I know that it Docbook within OFBiz can be fixed. See link to a thread I started about it https://s.apache.org/dxBa https://issues.apache.org/jira/browse/OFBIZ-6015 Honestly if I'd had the technical ability to do it, I would have done a Webhelp Proof of Concept (PoC) already and put a demo of it into the trunk for people to look at. At least with something working it's easier to make a decision to continue or not. The Webhelp add on was implemented so that it could exist alongside our existing content manager online help so it we could used to gradually switch over rather than disable one over the other. If I could have at least a volunteer developer to help me then I'd be willing to try to fix the docbook implementation. We've just done a 16.11 release so probably won't be doing another until around November (I'm only guessing here!) so there is a window of opportunity to see if we can try something. If fixing docbook doesn't work then we know loud and clear that we need to remove it and use something else. Either way we have progress and for me that's what we need. So you can probably see that I'd like us to try and first fix the docbook implementation that we have. Thanks Sharan On 2017-06-08 10:54 (+0200), 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 > > >
