Hi Taher Thanks for summarising the main points and also proposing a potential way forward.
I'd be happy with this solution and I really like the fact that we could incorporate any AsciiDoc contributions too. +1 from me Thanks Sharan On 2017-06-12 23:55 (+0200), Taher Alkhateeb <slidingfilame...@gmail.com> wrote: > Hi Michael, Sharan, All > > Reading through your posts flicks a few light bulbs. I think more or less > we can summarize the highlights: > - It's useful to have two sources of documentation: Long documentation in > the wiki and short functional documentation inside the code base > - Sharan prefers to keep DocBook (me too!) as this provides the least > amount of work compared to building from scratch a new solution. > - Michael prefers to minimize the the sources of documentation (me too!) to > focus efforts and ease contribution. > > To try and focus this thread, may I suggest that we proceed as follows: > - If everyone agrees on keeping DocBook, we can create a new JIRA to fix > the implementation (I can try to help out, volunteers are more than > welcomed) > - We create a second JIRA that depends on completing the above JIRA for > inclusion of the webhelp component. It might need to be reimplemented in a > cleaner, more efficient way. > - We accept AsciiDoc contributions from users subject to converting them to > DocBook before inclusion in the code base (either committer or contributor > can use the conversion tools). > - We go ahead and proceed with the documentation update plan including the > latest thread by Michael on how to cleanup the wiki and initiatives by > Sharan to cleanup the documentation in the code base. > > WDYT? > > Cheers, > > Taher > > On Mon, Jun 12, 2017 at 1:07 PM, Michael Brohl <michael.br...@ecomify.de> > wrote: > > > Hi Sharan, > > > > see my remarks inline... > > > > Regards, > > > > Michael > > > > Am 12.06.17 um 11:09 schrieb Sharan Foga: > > > >> 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. > >> > > > > I agree that we should not only focus on documentation in the code. That > > would be approach well suited for a more technical project like Freemarker. > > We have to provide a good technical documentation PLUS a good user > > documentation for the functional part, describing business processes, how > > to configure them etc. > > > > The latest questions in the user list clearly show that we need more > > how-to... documentation and easy entry points for users to find that > > documentation. > > > > So I thin we need: > > > > * a good Javadoc and surrounding technical documentation for developers > > * a good business process description, how-tos and examples > > * a context-related help inside OFBiz (maybe also with language support) > > * a general high-level overview of the features OFBiz and it's plugins > > provides (managament summary, marketing overview) > > > > It would be great if we could form some named teams to take care of this > > and who continuously work on it. > > > > > >> 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. > >> > > > > I think the best approach would be to provide a good structured, release > > specific documentation which we can generate to multiple output formats > > like html and pdf (see Camel). > > If we manage to somehow index the html help (url and anchors) we could > > simply save the link/anchor in the webhelp content and serve it either from > > the official web page or put it in the project. > > > > That would kill two birds with one stone. > > > > Because of it's complexity I would strongly suggest to have as few as > > possible sources of documentation. > > > > 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. > >> > > > > I'll see if we can provide some help with this, have to check our > > ressources. > > > > > > > >> 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 > >>>> > >>>> > > > > >
