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 <rwhee...@artifact-software.com > 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: rwhee...@artifact-software.com > skype: ronaldmwheeler > phone: 866-970-2435, ext 102 > >
