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
