Some comments on DITA for a small group

[Ron Wheeler]

This was part of a discussion on the DITA forum.

Ron


-------- Forwarded Message --------



Hi Ann:

As an information architect that has converted numerous products and
acquisitions to XML, I can tell you that you are on the right track in
considering structured documentation and DITA from the get-go. I cannot
tell you how many "small" products and acquisitions I have subsequently
converted that started out on the premise that they would not be large
and would not be translated. They were all subsequently wrong.

They became increasingly large and complex with eventual translation
requirements as they attempted to penetrate international markets with a
huge cost burden that undermined any initial "savings" going with
apparently cheaper, easier solutions. I'm not sure why so many companies
start with the premise that they will not be successful!

The subsequent conversion tasks are extremely expensive, though a
one-time cost. The savings moving to structured documentation and
XML/DITA at a later date more than make up for the investment, many
times over, especially when translations enter the picture. But it's
best not to incur the conversion cost in the first place.

In my opinion, it's better to start off with the premise of scalability
from the get-go and bypass the later conversion tasks altogether. Most
large companies that I know of these days are already using DITA with
some editor and CMS solution or another.

At a previous company, what we did was take a sample set of content into
XML and then tried the various editor solutions available at the time,
generating outputs along the way. You can download trials from all the
major DITA vendors.

I will cut to the chase. My own bias these days is toward oXygen for
technical reasons. The editor is mature, bundles DITA OT, and provides a
version of WebHelp that you can generate out of the editor. The editor
provides a profiling method for creating custom outputs per your
requirements. As a software developer, you should have no issue creating
custom plug--ins based on DITA OT.

DITA OT is important because it is, as the name indicates, an Open
Toolkit that you can modify for your own requirements without vendor
lock-in.  Need a new help output? Create another plug-in meeting the
specific requirements of the day and keep rolling. If you want to
jettison oXygen for some reason at a later date, keep your plug-ins and
use a different editor on top of OT. As I see it, editors come and go,
but your content and data will persist through time. That's been my
industry experience to date and I don't expect it to change.

I personally use PTC Arbortext as an editor a lot, but you will need to
integrate your own DITA OT modifications into the editor workflow and
probably purchase a licence for the WebHelp. I find this to be a real
pain when wanting to use open source for the build chain, as much as I
like Arbortext with the PTC DITA Application. You could buy a license of
WebHelp from the oXygen group and use it as an external plug-in, but
there are other WebHelp solutions worth considering. I like the plug-in
route myself because it follows the existing, modular OT model and does
not require lock-in to an editor.

If you're really adventurous, you can now build build your own WebHelp
type solution using HTML 5 and dita4publishers plug-ins with OT, but you
will need to invest development time into this route. Personally, I
think it would be cheaper and faster to simply buy a license for
oXygen's external WebHelp plug-in and modify that for company look and
feel requirements.

The other route is to use a proprietary replacement for OT, still using
DITA, with possible workflow enhancements and value-add in the CMS,
which can be very real factors, especially in larger organizations.
Personally, I want my content formats and build chain to be open source
so I can switch editors and CMS as needed. I don't mind using
proprietary components in the workflow, but the fundamentals of the
source and final build outputs must remain open in my view to
future-proof my information architecture investment.

Troy Klukewich
InfoDev Manager
Oracle Corporation



On Wed, Jun 17, 2015 at 4:48 AM, [hidden email]
<mailto:[hidden email]> [dita-users] <[hidden email]
<mailto:[hidden email]>> wrote:

    Hello,

    My company (software provider with ~100 employees) is finally
    accepting the challenge to put a dedicated documentation project in
    place with the aim of having up to date product documentation
    created, maintained and available to internal users and customers.
    This is something we don't currently have and it is hurting us.

    I am a software developer with an interest in training and
    documentation and I have been asked to instigate this project. I am
    finding it very difficult to identify which tool/solution we should
    go with i.e. DITA or non-DITA.  I absolutely want us to have
    structured content where the documentation admin can create
    templates which SMEs fill in.  I want something like tri-pane
    webhelp that has good search functionality ideally using meta data
    added by the SME. Since we don't have a Tech Writer team or that
    expertise I feel that going the DITA route might mean we will have
    nothing to show for a very long time.  However, if we go with a
    non-DITA solution provider I am afraid we will have unstructured
    documentation that will prove difficult to maintain and the project
    will fail.

    With this basic information, can anyone experienced out there advise
    on what path I should consider in relation to the environment in
    which we will fill in our product documentation content?

    Any advice appreciated,

    Thanks in advance,

    Ann Jensen




__._,_.___
------------------------------------------------------------------------
Posted by: Troy Klukewich <[hidden email]>
------------------------------------------------------------------------


Visit Your Group
<https://groups.yahoo.com/neo/groups/dita-users/info;_ylc=X3oDMTJmOHVlcHRjBF9TAzk3MzU5NzE0BGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDdnRsBHNsawN2Z2hwBHN0aW1lAzE0MzQ1NDk2ODY->


  * New Members
    <https://groups.yahoo.com/neo/groups/dita-users/members/all;_ylc=X3oDMTJnbmJiZnBoBF9TAzk3MzU5NzE0BGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDdnRsBHNsawN2bWJycwRzdGltZQMxNDM0NTQ5Njg2>
    4

Yahoo! Groups
<https://groups.yahoo.com/neo;_ylc=X3oDMTJlcWg4bzFmBF9TAzk3NDc2NTkwBGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDZnRyBHNsawNnZnAEc3RpbWUDMTQzNDU0OTY4Nw-->

• Privacy <https://info.yahoo.com/privacy/us/yahoo/groups/details.html>
• Unsubscribe
<mailto:[hidden email]?subject=Unsubscribe> •
Terms of Use <https://info.yahoo.com/legal/us/yahoo/utos/terms/>

__,_._,___

[Paul Foxworthy]

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) 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: [phone]
Fax: [phone]
Web: http://www.coherentsoftware.com.au/
Email: [hidden email]

Small. Complete. Perfect.
Your business with BonsaiERP.
http://www.bonsaierp.com.au/

[Jacques Le Roux]

Le 19/06/2015 03:44, Paul Foxworthy a écrit :

> 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) online
> service, which is free for open source projects. See
> https://wiki.openstack.org/wiki/Documentation/Translation.

Here Eric Raymond explains AsciiDoc completes Docbook http://www.tldp.org/HOWTO/html_single/DocBook-Demystification-HOWTO/#AEN183

BTW did you know that Groovy documentation is done with AsciiDoc (actually  AsciiDoctor) http://www.groovy-lang.org/documentation.html not bad hé

>
> 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 been using Oxygen for years, until they suppressed their Academic license, the annual license passed from 16 euros to 200 :/
The free tools in Eclipse are enough for my work with OFBiz, and I even encounter less edition issues (yes Oxygen sucks sometimes, believe me)

Jacques

>
> 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
>

[Ron Wheeler]

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: [phone]
> Fax: [phone]
> Web: http://www.coherentsoftware.com.au/
> Email: [hidden email] <mailto:[hidden email]>
>
> Small. Complete. Perfect.
> Your business with BonsaiERP.
> http://www.bonsaierp.com.au/

--
Ron Wheeler
President
Artifact Software Inc
email: [hidden email]
skype: ronaldmwheeler
phone: [phone], ext 102

[Ron Wheeler]

DITA not only supports i18n but has specific features to reduce the
translation management effort.
For instance:
You can identify terms that should not be translated "Tomcat", "Windows".

You can provide translations of phrases that are frequently used so they
do not get translated more than once. "Cancel", "Open for Business".
"This feature requires administrative privileges.", etc.
  This also adds consistency in a single language and make customization
of labels easier. "This feature requires administrative privileges."
should not come up as "Administrative role required." or "You need admin
privs to do this." If you have decided to use "HST" to replace "VAT" on
a label, you only have to change one term to convert all of your docs.

You can create country, industry-specific or language-specific manuals
easily.

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: [phone]
> Fax: [phone]
> Web: http://www.coherentsoftware.com.au/
> Email: [hidden email] <mailto:[hidden email]>
>
> Small. Complete. Perfect.
> Your business with BonsaiERP.
> http://www.bonsaierp.com.au/

--
Ron Wheeler
President
Artifact Software Inc
email: [hidden email]
skype: ronaldmwheeler
phone: [phone], ext 102

[Paul Foxworthy]

Hi Ron,

On 20 June 2015 at 01:21, Ron Wheeler <[hidden email]>
wrote:


> 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.
>

 There is a plugin for IntelliJ Idea I use:
https://github.com/asciidoctor/asciidoctor-intellij-plugin

Cheers

Paul Foxworthy

--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Phone: [phone]
Fax: [phone]
Web: http://www.coherentsoftware.com.au/
Email: [hidden email]

Small. Complete. Perfect.
Your business with BonsaiERP.
http://www.bonsaierp.com.au/

[Paul Foxworthy]

Hi Ron,

On 20 June 2015 at 01:36, Ron Wheeler <[hidden email]>
wrote:

> DITA not only supports i18n but has specific features to reduce the
> translation management effort.
> For instance:
> You can identify terms that should not be translated "Tomcat", "Windows".
>
> You can provide translations of phrases that are frequently used so they
> do not get translated more than once. "Cancel", "Open for Business". "This
> feature requires administrative privileges.", etc.
>  This also adds consistency in a single language and make customization of
> labels easier. "This feature requires administrative privileges." should
> not come up as "Administrative role required." or "You need admin privs to
> do this." If you have decided to use "HST" to replace "VAT" on a label, you
> only have to change one term to convert all of your docs.
>
> You can create country, industry-specific or language-specific manuals
> easily.

You're starting to sell me on this!

Would it be possible to use the OFBiz resources like
applications/accounting/config/AccountingEntityLabels.xml as an input? I
understand the translated terms would need to be in DITA format to
integrate with DITA documentation. But could be use the same property keys
as in OFBiz (e.g. AcctgTransType.description.AMORTIZATION) and do you think
there's any prospect of using XSLT to transform our resources into DITA
format?

Thanks

Paul Foxworthy

--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: [phone]
Fax: [phone]
Web: http://www.coherentsoftware.com.au/
Email: [hidden email]

Small. Complete. Perfect.
Your business with BonsaiERP.
http://www.bonsaierp.com.au/