OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Fwd: Possible Proposal to Discuss: Product names and reuse

Please review Christian Lieske's Best regards, Practices document, especially no. 22. Perhaps we should consider adding loc.note to DITA 1.3

Sent from my iPad
JoAnn Hackos
Comtech Services Inc
710 Kipling Street Suite 400
Lakewood CO 80215

Begin forwarded message:

From: "Lieske, Christian" <christian.lieske@sap.com>
Date: January 28, 2013, 3:12:17 AM MST
To: JoAnn Hackos <joann.hackos@comtech-serv.com>, "DITA Translation Subcommittee" <dita-translation@lists.oasis-open.org>
Cc: "cyao@csoftsolution.com" <cyao@csoftsolution.com>, "matt.arney@csoftintl.com" <matt.arney@csoftintl.com>, Andrzej Zydron <azydron@xml-intl.com>, Rodolfo Raya <rmraya@maxprograms.com>
Subject: RE: Possible Proposal to Discuss: Product names and reuse

Hi JoAnn,


Thanks for providing an opportunity to look at DITA again.


Since I feel that I am lacking some background information, I don’t feel in a position to provide detailed feedback. However, my feeling is that the discussions should consider the following section of the W3C Best Practices for XML Internationalization:






From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com]
Sent: Dienstag, 15. Januar 2013 18:17
To: DITA Translation Subcommittee
Cc: cyao@csoftsolution.com; matt.arney@csoftintl.com; Lieske, Christian; Andrzej Zydron; Rodolfo Raya
Subject: Possible Proposal to Discuss: Product names and reuse


Dear members of the DITA Translation Subcommittee and associated friends.


We have been discussing the issue of parts of speech and keyrefs of individual words at the DITA TC. Troy Klukewich mentioned a solution he used some years ago that the committee found intriguing. Some discussion has ensued to introduce an attribute for part of speech for DITA 1.3. 


I would like to get feedback from each of you about the feasibility of such a proposal to facilitate translations and overcome the problems of translating single words that have been conref'd or keyref'd.


Please let me know if you believe it would be worthwhile to pursue a proposal to better handle parts of speech in translation of DITA reused content.


Best regards,





JoAnn T. Hackos, PhD


Comtech Services Inc.

710 Kipling Street, Suite 400

Denver, CO 80215





From: Troy Klukewich <troy.klukewich@oracle.com>
Organization: Oracle Corporation
Date: Tuesday, January 15, 2013 8:20 AM
To: DITA TC <dita@lists.oasis-open.org>
Subject: Re: [dita] Product names and reuse


I've been watching people hack DITA for years trying to deal with product and sometimes feature names in a consistent XML-like way.

Prior to DITA, I worked on a similar XML architecture (concept/task/reference) with a custom processing kit. With numerous product names and feature names in an almost continual state of flux, we decided to treat product names and feature names as global variables with a mapping file for the literal strings (in English). The literal product and feature names were then inserted at build time and appeared in the output. (We used editor maps to virtually display the same content in the authoring editor for the convenience of writers.)

The inherent problem with this approach is that the mapped strings must be translatable. As products and features can have plurals and possessives, these must also be handled in the mapping file and accounted for in the variable element.

It is not permissible for instance to have a construct like: <varProduct>s or <varProduct>'s appear in the XML content as translators will translate the mapping file elsewhere and not be able to easily reconcile the plurals and possessives in the content itself. (I think these were the only variations we had to worry about, but it's been a while I admit.)

So we expanded the variables schema to include attributes for plurals and possessives in the variable elements themselves, which the writers selected at authoring time. This required some training as the process is a little abstract. You do not for instance add an apostrophe to the product XML element when building a possessive, but select an attribute in the editor and let the build do it.

The mapping file then contained base product and feature names plus their plural and possessive forms.

A build engineer maintained the mapping files and creation of new variable codes supporting first instance of new features and product names. We had workflow where writers would contact the engineer when needing a new variable value that was not already covered, though most were set up at the beginning of a release with the identification of new products and features.

The upside of this approach is that the output for product or feature names was entirely automated. If feature or product names changed late, as often happens in the software industry, we tweaked the mapping file at build time and the writers didn't have to do anything at all.

As far as graphics and special formatting in some product and feature names went, we handled this purely at build time with special processing instructions for the applicable variables. Otherwise, we're really talking about desktop publishing practices in XML and I'm not sure if DITA should inherently support this or if those features should be handled with a custom processing chain for those particular elements. Strictly speaking, formatting and graphics are a rendering operation during build time. In XML, writers shouldn't have to care about how to format a product name or add special graphics to it. That's my philosophy as an anti-DTP guy.

I'm sure there are other ways to accomplish the same thing, but this global mapping architecture worked really well, saved a lot of time, and was just generally really convenient all around for everybody once implemented.

In short, I inherently think of product and feature names as variables and whatever architecture handles and processes them must be able to address the issues of variables in text.

Troy Klukewich
Manager & Information Architect
Fusion HCM
Oracle Corporation

On 1/14/2013 1:43 PM, Kristen James Eberlein wrote:

A thread about difficulty in reusing products names has cropped up on the dita-users list.

Problem descriptions
1) Information architects or editors design a reuse strategy that revolves around using the <ph> element to hold product names. They then discover that they cannot put a <ph> element within any of the following elements:

  • <uicontrol>
  • <wintitle>

2) Another team decides to use <keyword> to hold their product names -- better choice -- but they also discover that they cannot put a keyword element within a <wintitle> element; they have to duplicate their product names within <text> elements for use within <wintitle> elements. And the <tm> element is not available within <text>.

3) Yet another team is stymied because their product name contains typographic formatting (superscript, subscript, bold or italic formatting, an inline image) that cannot be contained in either the <keyword> or <text> element. And while the text element can nest, the @outputclass attribute is not available.

Architects and the writers are caught between a strong desire to reuse content and ensure that product names are consistently used, and a need to have their company's name render correctly.

Thoughts about how we might try to address this problem? And sense about how big (or small) this problem is?


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]