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 >>>> >>>> > >
