I'm pretty much sitting this one out (seems to have jumped right into the tech selection and I don't understand OFBiz well enough yet to be useful as a writer-contributor so I wouldn't be able to offer much quality input), but for what it's worth the most important considerations for a typing architecture are:
1. The project's business needs (e.g. "No XML files!") 2. Making sure the single-sourced files can be puked out into as many useful end user formats as possible (e.g. context-sensitive help, wiki, etc.) 3. Making sure a maximum number of writer-contributors can hit the proverbial ground running without needing to learn new processes One thing I can offer for now is editing skills, but that involves potential toe-stepping. Perhaps I could transform that solid Prezi presentation into Sozi format so its SVG output could be embedded into any OFBiz web page. If the original author is cool with that (can't remember who it was), let me know. On 15-05-28 04:44 AM, Jacques Le Roux 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 >>>>>> >>>>> >>>> >>> >>
