In stead of adding another set of complexities and potential orphaned endeavours (asciidoc, markdown, etc) to the mix of https://www.openhub.net/p/Apache-OFBiz/analyses/latest/languages_summary#dingus-row, I suggest applying something that contributors already have experience and/or are comfortable with.
Please also remember that - to state the obvious: as this constitutes a 'code-change' - consensus is required. 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 Thu, May 28, 2015 at 1:44 PM, Jacques Le Roux < [email protected]> wrote: > And finally: > Read theStandardization section at http://en.wikipedia.org/wiki/Markdown > Also this one is maybe a bit biased (done by Dan Allen who supports > AsciiDOc) but still an interesting comparison: > https://gist.github.com/mojavelinux/5870367 > check > Asciidoc > https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc > vs > Markdown > https://github.github.com/github-flavored-markdown/sample_content.html > > Jacques > > > Le 28/05/2015 13:24, Jacques Le Roux a écrit : > >> Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/ >> >> Jacques >> >> Le 28/05/2015 13:19, Jacques Le Roux a écrit : >> >>> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining >>> interest see >>> http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's the >>> same spirit than Json againt XML...Though Markdown is not XML, but Dita is. >>> Also AsciiDoc offers a lot of export possibilities, see >>> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages >>> >>> Anyway we will need a community consensus... >>> >>> Jacques >>> >>> Le 28/05/2015 12:29, Taher Alkhateeb a écrit : >>> >>>> Hi Jacques and all, >>>> >>>> If you want a simple documentation language then markdown comes to >>>> mind. It is simple, beautiful, mature and well supported in terms of tools >>>> and probably covers the 90% of cases needed by everyone. So throwing >>>> another suggestion in the mix. >>>> >>>> Taher Alkhateeb >>>> >>>> ----- Original Message ----- >>>> >>>> From: "Jacques Le Roux" <[email protected]> >>>> To: [email protected] >>>> Sent: Thursday, 28 May, 2015 12:51:13 PM >>>> Subject: Re: [DISCUSSION] OFBiz Online Documentation >>>> >>>> That sounds quite an interesting way Ron. >>>> I also believe we should get rid of DocBook in favour of DITTA or maybe >>>> even AsciiDoc (the last smart guy) as we already discussed at the bottom of >>>> https://issues.apache.org/jira/browse/OFBIZ-4941 >>>> I also like the idea of separating the documentation from the project >>>> (Yippee our 1st sub-project Ron ;) ). >>>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like >>>> outlined Sharan (damn can't find the link again), it has a lot of features, >>>> notably when it comes to transform formats... and anyway it's our wiki >>>> support... >>>> >>>> Jacques >>>> >>>> Le 27/05/2015 17:55, Ron Wheeler a écrit : >>>> >>>>> On 27/05/2015 10:50 AM, Michael Brohl wrote: >>>>> >>>>>> Hi Sharan, >>>>>> >>>>>> I had not the time to think more about your proposal but I can >>>>>> quickly answer your followup questions, see inline... >>>>>> >>>>>> Am 27.05.15 um 15:34 schrieb Sharan-F: >>>>>> >>>>>>> Hi All >>>>>>> >>>>>>> I'm still looking for some community feedback on this proposal and >>>>>>> approach >>>>>>> and now I have a couple of extra questions. >>>>>>> >>>>>>> To any OFBiz Service providers out there – how do you manage the >>>>>>> online help >>>>>>> when you install or implement OFBiz? (Is it left as it is, do you >>>>>>> remove it >>>>>>> or do you create some new online help?) >>>>>>> >>>>>> In most of our projects, the existing online help is not used at all. >>>>>> The nature of our projects are mostly eCommerce and portal systems with >>>>>> another ERP backend like SAP. So the OFBiz backend is either not used >>>>>> at all or only a small part is used. We do trainings with the end users >>>>>> then >>>>>> and sometimes write some kind of manual which describes the backend >>>>>> use in context to the customer specific processes. >>>>>> >>>>>> I think there was only one project in the past 13 years which used >>>>>> the online help with partly modified texts. >>>>>> >>>>> This is where DITA would be a big help since you could customize the >>>>> topics that you need to change and leave the rest as is. >>>>> I do this with our ADTransform product wherein I write a DITAMAP for a >>>>> customer that pulls in common topics from the main manual library and >>>>> customized topics written for each customer where we are providing the >>>>> ETVL scripts and want to document the customers particular ETVL workflow. >>>>> >>>>> This short article introduces a good methodology for handling language >>>>> customization. >>>>> >>>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/ >>>>> It probably overly detailed for this point in the discussion but I did >>>>> want to point out how a single overall map can be used to produce manuals >>>>> in >>>>> different languages that are guaranteed to at least contain the same >>>>> topics. >>>>> It also shows how a multilingual manual would be set up as a project >>>>> and generated (it shows the linux command line not the IDE as I would >>>>> recommend) for those who like to get into the nuts and bolts early. >>>>> >>>>> >>>>> To the general community at large - what is the overall feeling about >>>>>>> extracting the online help, updating it and then packaging it as a >>>>>>> separate >>>>>>> project deliverable that can be easily integrated back into OFBiz? >>>>>>> >>>>>> Mmmhh, we have to make sure that the contents of the online help are >>>>>> in sync with the development and that it is easily editable for project >>>>>> specific changes. Then I'm fine with it. >>>>>> >>>>> For our ADTransform ETVL product which is a batch process(no on-line >>>>> help possible or needed) , I use DITA for the manual and edit it in my IDE >>>>> and >>>>> store it as an SVN (I know that I am old fashioned!) project with my >>>>> code so I can edit the docs and code together in the IDE. >>>>> I produce the manual using Maven within the IDE. >>>>> >>>>> This makes it easier to keep both in synch by changing whichever file >>>>> is wrong. Sometimes I write the manual topic first so I capture the spec >>>>> before coding it and sometimes I think of good ideas while coding that >>>>> changes the topic in the manual so it is nice to have both files open in >>>>> the >>>>> IDE at the same time. >>>>> >>>>> It does encourage me to write better specs since I have to think out >>>>> and explain in plain language what the new feature is going to do for the >>>>> user >>>>> and clearly describe the meaning and possible ranges of values of each >>>>> of the configuration parameters. >>>>> >>>>> I also feel better knowing that the effort spent on writing a clear >>>>> spec will save (or eliminate) documentation effort later. Counters the >>>>> WISCY >>>>> syndrome. >>>>> >>>>> I'm focussing on the approach first. I think that once we have had the >>>>>>> discussion about that and reach a concensus can we start discussions >>>>>>> around >>>>>>> the technology and options to achieve it. >>>>>>> >>>>>>> Thanks >>>>>>> Sharan >>>>>>> >>>>>>> Regards, >>>>>> >>>>>> Michael Brohl >>>>>> ecomify GmbH >>>>>> www.ecomify.de >>>>>> >>>>>> >>>>> >>>> >>> >>
