[Comment on ITS WD] Editorial comments from RI

These are non-weighty editorial comments or suggestions.  I will send more important comments via separate emails.

THESE ARE COMMENTS FOR SECTION 1


1.1.1  Vendors of ...
This type of users encompasses...
This type of user includes...

1.1.1 Content producers
This type of users comprises...
This type of user comprises...

... other types of content authors.
... other types of content author.


The burden of inserting markup should be ...
The burden of inserting markup can be ...


1.1.2 Eg 1
I find the links such as [EX-ways-to-use-its-1.xml] very strange.  Why not just say "Link to source text" or some such thing.


"A content author or information architect uses markup at the top of the document to identify a particular type of element or context in which the content should not be translated."
I think you should add further commentary right here (briefly) on what the example shows.  For example:
"Example 2 shows how you could set a rule to say that no dt elements in a document should be translated."


A processor may inject markup...
A processor may insert markup...


"A processor may inject markup at the top of the document which links to ITS information outside of the document."
I find myself wondering, How does this work?


"A schema developer integrates ITS markup declarations in his schema to allow users to indicate that specific parts of the content should not be translated."
I really think you need a third example here to make this clear.  I think an example of the content would work fine.


It's not immediately obvious which examples relate to which bullet points - you have to check.  It would be much better to do something like add "(Example X)" at the end of each line, to associate the point with the right example.
(Note that you can easily refer to examples by number using the i18n version of the xmlspec dtd, by pointing to the id of the example in a specref element.)


1.2 Motivation for ITS

Having read this after a while away from the document, I really think that the first part of this section should come before the previous section (1.1).  It is very high level introductory stuff.

Examples
I think it would help to split this seemingly long section.  I think that would make it more likely for people to read it.  You could insert a title "Typical problems" before the para "The following examples sketch...".


Examples
I think people will wonder what the problem is.  You say that the general issue is that there's a "lack of a standard, declarative mechanism which identifies which parts of an XML document need to be translated".  You also say "PhaseCode should not be translated; the title attribute sometimes has to be translated and sometimes must not be translated.". But you don't say why the approach in the example doesn't work, ie. why ITS is needed. Same for the following example. Example 6 is slightly better in this regard, but by then I'm beginning to wonder why there are 3 examples, all of documents with partially translatable content.  Are there systematic differences? I have to investigate that to come up with some ideas, but the text should spell this out for me.


Example 3
"In the example below, there are no clear mechanisms allowing one to know which string element needs to be translated."
Well, actually I think the question is which ones should NOT be translated, given that the default is translate=yes


1.3


"These mechanisms and data formats, sometimes called Localization Properties, however, possibly may be implemented"

'these mechanisms' refers to "This standard does not exhaustively cover all mechanisms and data formats which might be needed for configuring localization workflows or tools to process a specific format."
Either you need to say:
"This standard does not cover mechanisms and data formats..."
or 
"Certain mechanisms and data formats, sometimes called Localization Properties,..."

If you go the first route, you should probably say something like:
"This standard does not cover the mechanisms and data formats sometimes called Localization Properties, however these may be implemented using the framework described in this standard."


Note
...data formats that allows localization tools...
...data formats that allow localization tools...


...the "Trados DTD Settings" file, and the SDLX "Analysis" file.
should that be 
...the Trados "DTD Settings" file, and the SDLX "Analysis" file.

I think you can lose the : after 'are'


1.4

...need an efficient way for managing...
...need an efficient way of managing...


This specification responds to these requirements by introducing mechanisms for specifying ITS information in XML documents
is a bit complex - how about
To meet these requirements this specification introduces mechanisms that add ITS information to XML documents


" The ITS mechanisms for selection are:
  * as for XML documents, usable local (at the XML node to which it pertains) or globally (not at the XML node to which it pertains)
    * as for global usage: possibly in the target XML document or in a separate file"
This reads rather weird. At the very least local->locally or globally->global.
How about breaking the paragraph before "The ITS mechanisms for selection...", (since this is a slightly different topic, but sounds like a repetition if you arent' reading carefully), and rewording as:
"ITS selection mechanisms allows you to provide information about content locally (specified at the XML node to which it pertains) or globally (specified in another part of the document). Global selection mechanisms can be in the same document, or in a separate file."


Ease of integration
Only for some requirements additional child...
Only for some requirements do additional child...


1.5

literate programming language
meaning?

...to extract documentation in HTML, XSL FO or LaTeX forms...
'in' means 'into' or 'from' (ie. ',which is in')?  not clear what you're saying here
 

============
Richard Ishida
Internationalization Lead
W3C (World Wide Web Consortium)

http://www.w3.org/People/Ishida/
http://www.w3.org/International/
http://people.w3.org/rishida/blog/
http://www.flickr.com/photos/ishida/

Received on Tuesday, 4 July 2006 16:18:47 UTC