I meant to say 'in the issue'. Pierre Smits
*ORRTIZ.COM <http://www.orrtiz.com>* Services & Solutions for Cloud- Based Manufacturing, Professional Services and Retail & Trade http://www.orrtiz.com On Mon, Jan 19, 2015 at 4:13 PM, Pierre Smits <[email protected]> wrote: > Ron, > > Please put your insights and suggestions as comment to the issue. > > Best regards, > > Pierre Smits > > *ORRTIZ.COM <http://www.orrtiz.com>* > Services & Solutions for Cloud- > Based Manufacturing, Professional > Services and Retail & Trade > http://www.orrtiz.com > > On Mon, Jan 19, 2015 at 4:06 PM, Ron Wheeler < > [email protected]> wrote: > >> Separate the documentation into a sub-project and let the documentation >> team that are not software writers commit to the docs. >> >> Of course, the software committers would all be committers on the doc >> project. >> >> This would also allow the documentation to be tagged, branched and >> released separately. >> It is likely to be released more frequently than the software project >> which would be helpful. >> >> I would suggest that we consider including the demo data in the >> documentation project so that the demos could be improved and coordinated >> with the documentation so that the OOTB demo matches the documentation and >> the demo data can be used in examples and figures. >> >> >> Ron >> >> >> On 19/01/2015 8:35 AM, Jacques Le Roux (JIRA) wrote: >> >>> [ https://issues.apache.org/jira/browse/OFBIZ-4941?page= >>> com.atlassian.jira.plugin.system.issuetabpanels:comment- >>> tabpanel&focusedCommentId=14282494#comment-14282494 ] >>> >>> Jacques Le Roux commented on OFBIZ-4941: >>> ---------------------------------------- >>> >>> 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) >>> >>> >> >> -- >> Ron Wheeler >> President >> Artifact Software Inc >> email: [email protected] >> skype: ronaldmwheeler >> phone: 866-970-2435, ext 102 >> >> >
