CONREF best practices

[Andrzej Zydron <azydron@xml-intl.com>]

Hi Everyone,

As regards XML best practices in general please refer to my paper from 
XML 2004 USA which details many of the do's and dont's regarding XML 
localization:

http://www.idealliance.org/proceedings/xml04/papers/49/paper.html

As regards best practices concerning the use of the DITA conref element 
I would like to propose the following:

Great care should be taken regarding the use of the 'conref' element. 
Although the conref element may appear as a very efficient artifice to 
allow for the simple substitution of product names etc. allowing for the 
runtime resolution of given parameters this can cause grammatical 
problems with highly inflected and gender sensitive languages such as 
most Slavonic and Germanic languages.

What works extremely well for English or French source text can result 
in ungrammatical text for given target languages. Such an outcome is 
generally undesirable as it will reflect badly on the documentation 
concerned.

As a general rule the safest way to use conref is for the inclusion of 
grammatically complete sentences or phrases (those that can stand alone 
and do not rely on the surrounding context).

Never use conref to substitute common nouns or noun phrases such as for 
example 'hammer' or 'screw driver' etc.

Where the conref is used for proper nouns, such as 'Ford Focus' the the 
safest solution is to insure that the proper noun is always the main 
subject of the sentence, e.g.:

Do not use:

Driving the Ford Focus is an exhilarating experience.


Rather use:

The Ford Focus provides an exhilarating diving experience.

The subject of a sentence is in the nominative case and therefore does 
not normally require inflection.

The translators should also receive appropriate instructions to insure 
that the substituted proper noun is translated as the subject of the 
sentence.


Best Regards,

AZ

-- 


email - azydron@xml-intl.com
smail - c/o Mr. A.Zydron
	PO Box 2167
         Gerrards Cross
         Bucks SL9 8XF
	United Kingdom
Mobile +(44) 7966 477 181
FAX    +(44) 1753 480 465
www - http://www.xml-intl.com

This message contains confidential information and is intended only
for the individual named.  If you are not the named addressee you
may not disseminate, distribute or copy this e-mail.  Please
notify the sender immediately by e-mail if you have received this
e-mail by mistake and delete this e-mail from your system.
E-mail transmission cannot be guaranteed to be secure or error-free
as information could be intercepted, corrupted, lost, destroyed,
arrive late or incomplete, or contain viruses.  The sender therefore
does not accept liability for any errors or omissions in the contents
of this message which arise as a result of e-mail transmission.  If
verification is required please request a hard-copy version. Unless
explicitly stated otherwise this message is provided for informational
purposes only and should not be construed as a solicitation or offer.