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
--
Ron Wheeler
President
Artifact Software Inc
email: [email protected]
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
