Comments on the usage scenarios doc, sections 1-3

Editors' copy $Date: 2004/04/14 11:17:19

Here is my last review of sections 1-3 of the scenarios doc before a potential 
proofread when it really is done.


1 Introduction
--------------

"The goal of the Web Services Internationalization Task Force is to ..." - 
shouldn't that be Internationalization Web Services Task Force, as it's written 
on the linked page?


2.1 Basic Framework: Anatomy of a Web Service Interaction
---------------------------------------------------------

"The services is the function, ..." - remove final 's' from 'services'

2.1.2 Request
-------------

5. "If the SOAP message was decoded successfully, ... (that is, it was not in 
error) ... the provider agent will now attempt to invoke the service itself."
  - change of tense, would be better as -
    "If the SOAP message is decoded successfully, ... (that is, it is not in 
error) ... the provider agent attempts to invoke the service itself."


3.1 What are Internationalization and Localization?
---------------------------------------------------

subtitle "Do you even care?"  - just kidding

noted "web services" - assume doc will be scanned for all occurrences of "web 
services in any capitalization configuration and adjusted to the prescribed "Web 
services"

"Natural language text processing (parsing, spell checking, grammar checking are 
examples of these)" =>
"Natural language text processing; for example, parsing, spell checking, grammar 
checking."

"Alternate Calendars ... " => "Alternate calendars ... "

Add period after "Tax or regulatory regime", "Currency", "...and many more", or 
take the periods off the ends of the other bullet points.  Add a space after the 
ellipses in "...and many more".

Is there a W3C convention for referring to keywords and constants in 
programming/markup languages?  I think we should set off "lang" and "xml:lang" 
in the following statement "HTML for example uses the lang attribute to indicate 
the language of segments of content. XML uses the xml:lang attribute for the 
same purpose."

More on setting off a term "In this document, we will use the term locale as the 
name for this shorthand indicator for a user's particular set of international 
preferences." => 'locale' should be set off in some way, via underline or 
italics or bold or quotes or something.  We should be consistent, though, about 
how we set off a type of term.  In " ... this shorthand indicator for a user's 
particular set of international preferences." change 'for' to 'of'.

In the definition of Localization, why is "Locale" capitalized?  I don't see a 
need for it.  And again in the 2nd paragraph of Language Negotiation definition.

2nd paragraph of Language Negotiation definition - " ... the locale of "en-US" 
... " - 2 things, should we leave the hyphen as opposed to the underscore even 
though that convention is not yet established or standardized, and whatever we 
use, should it be set off by double quote marks?  back to establishing 
conventions for setting off types of terms.

Same paragraph "prefered" => "preferred", "infered" => "inferred", "vs" => "vs." 
- assume doc will be spell-checked.

3.1 last paragraph, change "and so forth" to "and others" or "and other 
entities" or something like that

3.1.1 Relationship of Locale to Natural Language
-------------------------------------------------

" ...  in the absence of other information, the language parameter can be 
helpful in guessing a relevant locale." - remove comma after 'information'

So, you _are_ deleting the old block, right?

3.1.2 I-025: Specifying and Exchanging International Preferences in Web Services
--------------------------------------------------------------------------------

"Web services, by contrast, must ... " =>
"Web services, in contrast, must ..."

Expand "RPC" the first time it's used, then use the acronym.

"There is no way to associate the string argument with locale functionality in 
the provider or available in the transport." =>
"There is no way to associate the string argument with locale functionality 
available in the provider or in the transport." - hmm, locale functionality 
available in the transport, is that even possible?  Identification, yes, 
functionality?

Need spaces after all the colons, e.g. "Description Scenario B:The ... " => 
"Description Scenario B: The ... "

"A legacy (existing) function ... " =>
"An existing function ... "

in Description Scenario C, "Accept-Langauge" => "Accept-Language"
"Existing locale negotiation mechanisms (such as Accept-Langauge in many 
application servers) rely on the container (formerly an Application server, but 
in this case the service provider) to populate this information. " =>
"Existing locale negotiation mechanisms, such as Accept-Language in many 
application servers, rely on the container (formerly an Application server, but 
in this case the service provider) to populate this information. "

Can we do something about the double colons in the Scenario As?  maybe replace 
the second colon with a dash or something.

"Scenario A: Different Locale Identifiers: Sender sends a request to a Provider 
and wants a specific locale and uses its identifier for that." =>
"Scenario A: Different Locale Identifiers - Sender sends a request to a Provider 
wanting a specific locale and uses its identifier for that."

" ... but the specific operation is slightly different than the sender's 
implementation and ... "=>
" ... but the specific operation is slightly different from the sender's 
implementation and ... "

" ... (zh-Hant -> zh which represents Simplified)" =>
" ... , for example zh-Hant, which represents Traditional Chinese, becomes zh, 
which represents Simplified Chinese." - set off zh-Hant and zh

"Scenario B: Senders sends a request to a Provider and wants a specific
locale and uses its identifer for that." =>
"Scenario B: Sender sends a request to a Provider wanting a specific
locale and uses its identifer for that."

Same Scenario, is the parenthetical (LCID -> Java) clear to our audience?  My 
guess is that it's pretty much Greek to anyone outside of i18n.  I think we 
should clarify the example, e.g. "For example, Microsoft Windows' Locale C? ID 
(LCID) is not the same as a Java locale identifier." or something like that

I'd like to pull the examples out of parentheses and give them more clarity in 
general in this section.

Scenario D needs a cleanup, I'm not sure exactly what is the intention so I 
can't rewrite it.

"Scendario E" => "Scenario E"  (Addison needs more sleep)  also another cleanup 
needed.

Scenario F needs cleanup.

Figure shows up in wrong spot, at least on Netscape 7.1 - it should be after 
Scenario A++ (the extra smart scenario)

3.2.1 Textual vs. Binary Representations
----------------------------------------

" ... binary representations and textual represenations." =>
" ... binary and textual representations."


"As an example, a floating-point number is represented in some binary format 
internal to an application, and is converted to a text ual format, with 
appropriate localization formatting (e.g. using a decimal comma rather than a 
decimal point for many European locales), for output to the user." =>
"As an example, a floating-point number is represented in some binary format 
internal to an application, and is converted to text with appropriate 
localization formatting for output to the user; for instance, the decimal in the 
formatted text may be represented by a comma, rather than a period."

"Nevertheless, most of them were carefully designed to be locale-independent, 
and are intended to be used locale-independent." =>
"Nevertheless, most of them were carefully designed to be locale-independent, 
and are intended to be used in a locale-independent manner."  or something 
similar which is not "Me Tarzan, you Jane" sounding

Note in the 2nd paragraph, the word "date" is set off via a change to a Courier 
type font - we could exploit this convention throughout the doc for keywords and 
constants.  Also note, the ISO standard here is written ISO 8601, that is, with 
a space after 'ISO'.  We should be consistent in the way we write the ISO 
standard names.  Same goes for RFCs, but RFCs don't have to be consistent with ISOs.

3.2.2 Locale-dependent XML Schema datatypes
-------------------------------------------

still need the Ethiopic example here

also, we have to decide if we're sticking with titlecase rules for section heads 
and apply it to all of them.



I'll put the rest of the comments in a separate mail (or mails)

Andrea

Received on Tuesday, 27 April 2004 20:24:27 UTC