[jira] [Comment Edited] (OFBIZ-4941) Proposal for a new help system

[Nicolas Malin (Jira)]

    [ https://issues.apache.org/jira/browse/OFBIZ-4941?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14282494#comment-14282494 ]

Jacques Le Roux edited comment on OFBIZ-4941 at 1/19/15 1:37 PM:
-----------------------------------------------------------------

I proposed to use AsciiDoc instead of Docbook because despite having [Oxygen in Eclipse|http://www.oxygenxml.com/xml_editor/eclipse_plugin.html#s2_docbook_documents_support] I found that it's not that easy to create documentation with Docbook, even with a specialised tool, so think about people with only XML.  I believe AsciiDoc opens more possibilities, like for instance as you said, supports of in-line GraphViz.

The idea is to use only AsciiDoc (everywhere) because , it seems to me, it has won the game among Lightweight markup formats.

Following is a bit unrelated, but you will see where I going with this
----
*I HATE CONFLUENCE* since they removed the possibility to use their own markup format. Actually I was already *HATING IT BEFORE*. Their rendering has always been erratic, to say the least.

Currently, despite ourt efforts, what we have in Confluence is a big ball of mud.

* Try for instance to replace a string in all a worskspace (not even speaking about several ones).  For instance, our complete domain name (actually a sub-domain name) is now _cwiki.apache.org/confluence_ when it was historically _docs.ofbiz.org_ before we moved from Contegix to the ASF Confluence instance. Of course this is impossible, can you believe it? So you have to do it *PAGE BY PAGE*, good luch with that! Just look at this link to have an idea.
https://cwiki.apache.org/confluence/dosearchsite.action?queryString=&where=conf_favorites&type=&lastModified=&contributor=&contributorUsername=&queryString=docs.ofbiz.org
* Moreover when it's only about a string it's somewhat doable, but just try to do it for URLs, yes it's a nightmare!
* Not only that but, as the ASF confluence instance is shared between a lot of projects, it's *SLOW*. Even barely reliable sometimes for long pages like the FAQ or the Minilang reference.
* The information given for a page is not able to distinguish wrong links
* There are a lot of obsolete, incomplete and confusing information in the wiki worskspace, and a lot of obsolete comments
* Try to remove obsolete comments, it's not only *SLOW* but you have to remove them *ONE BY ONE*.

I could go on and on. The only advantage Confluence had was how it handled access permissions. But with the last infra change due to spam, this is not even interesting now. We have to handle every contributors access ourselves. And sorry to say but from our current experience there is not a good ROI. People want to be contributors, but few contribute. We could handle that better using svn and AsciiDoc ourselves (committers). People really wanting to contribute would give us their contributions, through Jira for instance.

OK, it's just an idea for now, but I really would like to go this way. Using https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-docbook (would need to ask infra to install it for us) we could begin in DocBook format, before moving all in AsciiDoc.  Then we could use Buildbot to generate the documentation automatically using Pandoc. Where to post it is secondary, at the ASF of course! Using the demo VM seems the right place, we have already HTTPD serving the large videos there.

Of course this is not for tomorrow, but I believe it's the way to go if we want a really reliable, as complete as possible documentation. Without it OFBiz will never get the attention it deserves... :(


was (Author: jacques.le.roux):
I proposed to use AsciiDoc instead of Docbook because despite having [Oxygen in Eclipse|http://www.oxygenxml.com/xml_editor/eclipse_plugin.html#s2_docbook_documents_support] I found that it's not that easy to create documentation with Docbook, even with a specialised tool, so think about people with only XML.  I believe AsciiDoc opens more possibilities, like for instance as you said, supports of in-line GraphViz.

The idea is to use only AsciiDoc (everywhere) because , it seems to me, it has won the game among Lightweight markup formats.

Following is a bit unrelated, but you will see where I going with this
----
*I HATE CONFLUENCE* since they removed the possibility to use their own markup format. Actually I was already *HATING IT BEFORE*. Their rendering has always been erratic, to say the least.

Currently, despite ourt efforts, what we have in Confluence is a big ball of mud.

* Try for instance to replace a string in all a worskspace (not even speaking about several ones).  For instance, our complete domain name (actually a sub-domain name) is now _cwiki.apache.org/confluence_ when it was historically _docs.ofbiz.org_ before we moved from Contegix to the ASF Confluence instance. Of course this is impossible, can you believe it? So you have to do it *PAGE BY PAGE*, good luch with that! Just look at this link to have an idea.
https://cwiki.apache.org/confluence/dosearchsite.action?queryString=&where=conf_favorites&type=&lastModified=&contributor=&contributorUsername=&queryString=docs.ofbiz.org
* Moreover when it's only about a string it's somewhat doable, but just try to do it for URLs, yes it's a nightmare!
* Not only that but, as the ASF confluence instance is shared between a lot of projects, it's *SLOW*. Even barely reliable sometimes for long pages like the FAQ or the Minilang reference.
* The information given for a page is not able to distinguish wrong links
* There are a lot of obsolete, incomplete and confusing information in the wiki worskspace, and a lot of obsolete comments
* Try to remove obsolete comments, it's not only *SLOW* but you have to remove them *ONE BY ONE*.

I could go on and on. The only advantage Confluence had was how it handled access permissions. But with the last infra change due to spam, this is not even interesting now. We have to handle every contributors access ourselves. And sorry to say but from our current experience there is not a good ROI. People want to be contributors, but few contribute. We could handle that better using svn and AsciiDoc ourselves (committers). People really wanting to contribute would give us their contributions, through Jira for instance.

OK, it's just an idea for now, but I really would like to go this way. Using https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-docbook (would need to ask infra to install it for us) we could begin in DocBook format, before moving all in AsciiDoc.  Then we could use Buildbot to generate the documentation automatically using Pandoc. Where to post it is secondary, at the ASF of course! Using the demo VM seems the right place, we have already HTTPS serving the large videos there.
Of course this is not for tomorrow, but I believe it's the way to go if we want a really reliable, as complete as possible documentation. Without it OFBiz will never get the attention it deserves... :(

> Proposal for a new help system
> ------------------------------
>
>                 Key: OFBIZ-4941
>                 URL: https://issues.apache.org/jira/browse/OFBIZ-4941
>             Project: OFBiz
>          Issue Type: Wish
>          Components: ALL COMPONENTS
>    Affects Versions: Trunk
>            Reporter: Jacques Le Roux
>            Assignee: Paul Foxworthy
>            Priority: Minor
>         Attachments: HelpAccounting.jpg, HelpPerformanceReview1.jpg, HelpPerformanceReview2.jpg, HelpRoadmap.jpg, LICENSE.html, LicenseFiles.zip, OFBIZ-4941 POC HR Help.patch, OFBIZ-4941.patch, OFBIZ-4941.patch, OFBIZ-4941.patch, OFBIZ-4941.patch, OFBIZ-4941.patch, OFBIZ-4941.patch, WebhelpFiles.zip, WebhelpFiles.zip, WebhelpHRAppDocbook.zip, WebhelpHRAppDocbook.zip, content.7z, docbook diff.patch, docbook-xsl-1.77.1.zip, help_content.jpg, help_ofbizhelp.jpg, help_webhlep.jpg, helppdf.zip, jh.jar, ofbiz-common.xsl, webhelp.jpg
>
>
> Quoting Tom Burns at OFBIZ-4869
> {quote}
> This is a status update just to let anyone who is interested know that this item is being worked on.
> I started out using the OFBiz structure for help docs but after a while I needed/wanted something more expressive.
> Here is what I wound up using for development:
>     Java Help System http://java.net/projects/javahelp/content
>     DocBook 5: The Definitive Guide
>     http://www.docbook.org/tdg5/en/html/docbook.html
>     http://www.docbook.org/xml/5.0/
>     DocBook XSL: The Complete Guide
>     http://www.sagehill.net/docbookxsl/index.html
>     http://sourceforge.net/projects/docbook/files/docbook-xsl/1.77.1/docbook-xsl-1.77.1.zip
>     Help Master - FE for managing java help files. Best feature drag and drop TOC creates TOC matching file folder structure. Convenient launcher for viewing & testing. http://www.halogenware.com/software/helpmaster.html
>     XML Mind XML Editor - Free Personal Edition is far better then editing in Eclipse. download from http://www.xmlmind.com/xmleditor/download.shtml
>     Tutorial - DocBook editing with XML Mind XML Editor. Worth going through http://www.xmlmind.com/xmleditor/tutorial.html
>     Read Me First style guide from Sun (cost from Amazon 1 cent + shipping)
> Attached are some screen shots of the results.
> Every screen is/will be documented in a similar structure. This is as much for defining requirements and testing as for help. More work but worth it.
> The screenshots show a Java Help format generated using DocBook XSL. This will likely not be the final presentation format.
> Note the Performance Review screen shots do not match the trunk. There is a bug in update screen and I did some clean up of labels and drop-down list. There are issues like this all through the application so I did not want to get bogged down with patches at this time.
> {quote}

--
This message was sent by Atlassian JIRA
(v6.3.4#6332)