[jira] [Commented] (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=14280480#comment-14280480 ]

Ron Wheeler commented on OFBIZ-4941:
------------------------------------

http://www.slideshare.net/wapxana/documentation-with-open-source-tools  has a nice discussion of Docbook and AsciiDoc (slides - no audio so it take 3 minute to view 40 slides)
Never used AsciiDoc but have used Docbook and currently DITA.  I like structured XML since it removes formatting from content.
I have used Wikimedia and other languages with some of the characteristics of AsciiDoc. Don't like the wide variance of structuring syntax.

AsciiDoc:
-  has "include" which should help with structuring documents from fragments which encourages reuse.
- supported by multiple output processors - Ruby, Java JavaScript, etc which makes it easy to see that the content should have a long life as UI technology changes
- dynamic (on-screen) and static output (PDF) can be produced  from the same fragments might encourage better and more comprehensive documentation.
- supports in-line GraphViz so we might get more visual documentation that is uptodate.
- MIT license should be OK.

Will need to think about how to store content fragments to encourage reuse and increase consistency of documentation.

> 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: Jacques Le Roux
>            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)