Comments on sections 1-3 of usage scenarios

Reviewing sections 1-3 of Web Services Internationalization Usage Scenarios:

In formal writing, when referring to a particular word, that word is italicized 
or underlined, rather than enclosed in quotation marks.  It is much clearer to 
read it that way.  For example "In the sections that follow, you will see the 
word "locale" used ..." here "locale" is best italicized.  I don't recommend 
underlining as it tends to be associated with links.  The quotes make it look 
like it's a term only morons use or something, and we're referring to it just in 
case it's the only way the concept can be understood.  This occurs for all sorts 
of words and phrases throughout the text.  Similarly, if we're trying to 
introduce a key word or phrase, instead of surrounding it with quotation marks, 
it should be in bold, or bold italic, or even just italic.  I can go through an 
edit and do this, if you'd like.

Also, it would read much more easily if the parenthetical comments were limited. 
  Many could just be enclosed in commas.

2.1 Basic Framework: Anatomy of a Web Service Interaction

In the diagram, the purple arrows don't appear to be discovery, they simply get 
or input the WSDL.  Of course, color is subjective, and one could call those 
arrows "fuchsia" and call the discovery arrows "purple", but then that would 
leave no blue arrows.  Unless I'm misunderstanding the diagram?

2.1.1 Discovery

"It may also contain contextual information, either required or options, 
generally contained in headers, such as the information required for 
quality-of-service, security, transactionality, and so forth."
  - awk, how about:
"It may also contain required or optional contextual information for other areas 
of the service, such as quality-of-service, security, transactionality, and so 
forth.  This information is generally contained in headers."

2.1.2 Request

"5. ... recognized, and valid for a service supported by the provider agent 
(e.g. it was not in error) ..." - replace "e.g." with "i.e.", if you want to 
know why, ask.

3.1 What is Internationalization?

"Internationalized software responds to changes in "locale" or other 
international preferences. Some examples of changes to behavior include:"
  - no list, the next text sequence is:
"There are many capabilities that internationalization might enable in a Web 
service. Some of these preferences might include:"
- (the previous 2 sentences don't really go together)soooooooo, what are we 
talking about here? Changes to behavior, or enabling preferences?  Or both, and 
there's a missing list?

3.2 What are Locales?

"The creation and translation of these materials into other languages is 
typically called "localization" and this process is commonly confused with the 
broader topic of internationalization."
  - I would not call i18n a broader topic, as that implies that l10n is a subset 
of it.  How about:
"The creation and translation of these materials into other languages is 
typically called "localization" and this process is commonly confused with 
internationalization."
We've already defined i18n earlier in the document.  If that definition doesn't 
serve, then we need to clarify it.

"Some of these preferences may be inferred ..." - what preferences?  It's not 
clear what is being referenced.

3.2.1 WSDL

"... locale-of-operation ... " the locale in which the service operates, or the 
locale setting for the service operation, or?  Is this a known term?  I think it 
would be more straightforward to just say "locale" here.

"This is because specific implementation decisions should be expressed as part 
of the service's signature: you may require additional or different data in 
future versions." - replace the colon with a semicolon

3.2.2 SOAP

"SOAP Processor implementations should be designed to recognize natural language 
information passed in the transport (such as HTTP Accept-Language) or in SOAP 
headers as defined in this document or in the specific implementation-dependent 
extension of this model and populate or set the appropriate values in the 
service's environment."
- punctuate as:
"SOAP Processor implementations should be designed to recognize natural language 
information passed in the transport (such as HTTP Accept-Language), or in SOAP 
headers as defined in this document, or in the specific implementation-dependent 
extension of this model, and populate or set the appropriate values in the 
service's environment."

I think it would be best to get rid of "And so forth."  If you feel something is 
needed, how about "Other platforms will have a similar process." or words to 
that effect.

3.2.3 Faults and Errors

"Fault message "text" elements must be labelled with an appropriate language 
identifier, as defined in XML 1.0. That is, an xml:lang tag containing an 
RFC3066 (or its successor) language identifier. "
=>
"Fault message "text" elements must be labelled with an appropriate language 
identifier, as defined in XML 1.0.  That is, an xml:lang tag containing an 
RFC3066 (or its successor) language identifier should be in the text markup. "

"If the transport provides the user's language preference (such as HTTP 
Accept-Language)" - replace parens with commas

"SOAP Processor" => "SOAP processor"

"Numeric (or ASCII-only alpha-numeric) error codes ... "
=>
"Numeric or ASCII alpha-numeric error codes ... "

3.3.1 Examples

"A value of this datatype such as '5' (referring to May in each year of the 
Gregorian calendar) cannot be converted to calendars that do not have their 
months aligned with the months of the Gregorian calendar."
=>
"A value of this datatype such as '5' referring to May in each year of the 
Gregorian calendar cannot be converted to calendars whose months are not aligned 
with those of the Gregorian calendar."

"Please note that there are formats that use conventions ..."
=>
"Please note there are formats that use conventions ..."
-- 
I have always wished that my computer would be as easy to use as my telephone. 
My wish has come true. I no longer know how to use my telephone.
-Bjarne Stroustrup, designer of C++ programming language (1950- )

Received on Wednesday, 24 December 2003 13:29:37 UTC