One of the nice things about DITA is that it does presume any editing
tool.
I use Eclipse/STS because I use it for everything else in the project -
SCM management, issue tracking, editing code and resources, compiling
and running unit tests and deployment to our Maven repo.
It is also open source.
Someone else might like to use another editor that hides the XML a bit more.
As long as the documentation source files are in DITA, we can
collaborate on the content.
DocBook has the same general characteristics since it also holds its
source in XML that is not editor dependent.
Confluence is completely different.
AsciiDoc has some of the same characteristics but I have not found an
open source product that provides auto-completion and code hinting and
validation for AsciiDoc.
Ron
On 18/06/2015 7:44 PM, Paul Foxworthy wrote:
Hi Ron,
Up to a point I agree we should be planning for scalability and
success. I totally agree we should plan from the beginning for
internationalisation, and if a toolset doesn't support that, we should
avoid it.
I am strongly in favour of good logical markup, so that we can
generate a range of different destinations. DITA is one specific way
to achieve good logical markup, but not the only one.
DocBook *does* support i18n. For instance, the OpenStack project is
using DocBook. Their i18n efforts use the Transifex (transifex.com
<http://transifex.com>) online service, which is free for open source
projects. See https://wiki.openstack.org/wiki/Documentation/Translation.
The message you quoted was an Oracle employee assuming professional
tech writers and investing in commercial software like Oxygen. For
DITA to be viable for us, I would argue it must be usable by
developers with open source tools. We can't expect people to invest
any money in order to document OFBiz. Even with free tools, expecting
people to directly edit XML in Eclipse or whatever is a still a
barrier that will restrict contributions from non-developers. Maybe
that limitation is acceptable if the results will be good enough, but
"scalability" in theory is no good to us if nobody contributes in
practice.
I have not contributed one line of documentation to OFBiz, and I am
very familiar with IDEs and XML. So I am not the best person to judge
these things. I will be interested in the experience of people doing a
proof of concept. I will be very interested in the experience of
people who don't know much about XML.
I don't need to be persuaded that DITA is good, or that it produces
good results. I would like to explore whether or not it's *useable* by
non-specialists with a little knowledge and training.
Cheers
Paul Foxworthy
--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia
Phone: (03) 9585 6788
Fax: (03) 9585 1086
Web: http://www.coherentsoftware.com.au/
Email: [email protected] <mailto:[email protected]>
Small. Complete. Perfect.
Your business with BonsaiERP.
http://www.bonsaierp.com.au/
--
Ron Wheeler
President
Artifact Software Inc
email: [email protected]
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
