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" <jacques.le.r...@les7arts.com> To: user@ofbiz.apache.org 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 >> > >
