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-pluginOn 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 ofre-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
smime.p7s
Description: S/MIME Cryptographic Signature
