Re: Tim's comments on requirements doc.

Hi Tim, hi all,

Thanks a lot for the comments. I would propose that we collect proposals  
until Monday next week. I could use Tuesday to make corrections (spelling  
errors etc.), if that's fine with Yves. We then could vote about the  
corrected version on Wednesday.

Cheers,

Felix

On Thu, 21 Jul 2005 01:27:32 +0900, Tim Foster <Tim.Foster@Sun.COM> wrote:

>
> Hey Folks,
>
> Here's my (very late) comments on the current editor's copy of
> http://www.w3.org/International/its/requirements/
> (sorry, this is a long mail!)
>
> They're mostly typos and grammar, I'll quote the original text of the
> document with '>' characters so you can easily find text in the
> original. I'll also mark the section I'm talking about.
>
> I'm not 100% confident of all of these suggestions, so perhaps someone
> could review these, in case I'm incorrect in suggesting these changes ?
>
> (it might be useful if each section refers to the wiki page it was
> generated from, that would make adding comments/suggested changes to the
> draft a lot easier...)
>
> Here goes :
>
> Section 1.1
>
>> The increasing usage of XML as a medium for documentation-related
>> content (e.g. DocBook as a format for related to user manuals) and
>
> "e.g. DocBook, being a format for writing structured documentation, well
> suited to computer hardware and software manuals."
>
> [ I used the answer to the "What is Docbook?" FAQ question from
> http://www.dpawson.co.uk/docbook/reference.html#d4e16 as a basis for
> this re-wording ]
>
> ---
>
> Section 1.3
>
>> Such usage would be similar to the <style> element in an HTML
>> document.
>
> Not sure, do we phrase it as "a HTML document" or "an HTML document" ?
> (guess it depends on whether you pronounce the 'H' in HTML as "haitch"
> or "aytch" : W3C folks any ideas ? )
>
>> Such approaches are not meant to describe the configuration settings
>> (i.e. localization properties) of localization tools for XML content.
>
> Can we rephrase this to :
>
> "Such approaches are not meant to describe the configuration settings of
> localisation tools for XML content."
>
> - we haven't yet introduced the term "localisation properties", so
> leaving it more generic would seem to make sense for now (this is
> related to my thoughts about the RecTranslatability section that I'll
> suggest in the wiki later)
>
> ---
>
> Section 1.4 Key Definitions
>
> Richard was going to work on the wording of this a bit, to perhaps
> suggest that these are possible definitions of l10n and i18n, but that
> other definitions are used elsewhere.
>
> ---
>
> 2.1.1 Description
>
>> terms that should not be translated or translated using a pre-existing
>> terminology list
>
> Perhaps rephrase to :
>
> "terms that either should not be translated or should be translated
> using a pre-existing terminology list"
>
>
>> The use of a standardized set of tags allows the authoring systems to
>> provide a common solution for these special markers across all XML
>> documents.
>
> Perhaps rephrase to (s/the authoring systems/authoring systems/)
>
> "The use of a standardized set of tags allows authoring systems to
> provide a common solution for these special markers across all XML
> documents."
>
> ---
>
> Section 2.1.2 Stakeholders
>
> Perhaps replace each list item starting with "The ..." to just "...",
> eg.
>
> "The technical writers developing authoring content"
> would change to
> "Technical writers developing authoring content"
>
>
> ---
>
> Section 2.2.1 Description
>
>> This list is used to provided a consistent terminology across the
>> different parts of the documentation.
>
> typo "provided" -> "provide"
>
>
>> The same markup can be used further down the project, during
>> translation, to help the translators match up the source terms with
>> their agreed-upon translations.
>
> Not completely clear what "the project" is. Perhaps rephrase to :
>
> "The same markup can be used at later steps in the translation process,
> to help translators match up source terms with their agreed-upon
> translations"
>
> likewise
>
>> The use of a common set of markers allows afor better re-usability of
>> the information across the different steps of the process and across
>> the various tools used to facilitate that process.
>
> Again, perhaps say which process we're talking about : the "translation
> process" or "localisation process" maybe ?
>
> ---
>
> Section 2.2.2 Stakeholders
>
> (similar comments as for section 2.1.2)
>
> ---
>
> Section 2.3.1
>
> (A few minor wording changes here)
>
>> For example: UI resources and message files, comments in the source
>> code to generate documentation, or even temporary XML storage
>> generated from proprietary formats for the time of the localization.
>
> Could we make the above a sentence ? Something like,
>
> "Examples of this, would be UI resources and message files, comments in
> the source code to generate documentation, or even temporary XML storage
> generated from proprietary formats for the time of the localization"
>
>> A software developer often needs to provide localization-related
>> information with the resources that will be translated.
>
> "A software developer often needs to provide localization-related
> information along with the resources that will be translated."
>
>> For instance, he or she needs to indicate that a string has a maximum
>> length because the program reads it using a fixed-length buffer.
>
> For instance, he or she may need to indicate that a string has a maximum
> length because the software processes it using a fixed-length buffer.
>
> ---
>
> 2.3.2 Stakeholders
>
> (same comments as before)
>
> ---
>
> 3.2.1 Challenges
> (wow, I even need to correct myself from time to time ;-)
>
>> in source files that translation tools can also be used to determine
>> which translation process
>
> should be :
>
> "in source files that translation tools can use to determine which
> translation process"
>
> ---
>
> 3.4.2 Notes
>
>> The xml:id attribute [XML ID] may be a mean to carry the unique
>> identifier.
>
> typo --
>
> "The xml:id attribute [XML ID] may be a means to carry the unique
> identifier.
>
> ---
>
> 3.6.1 Challenges
>
>> In order to simplify parsing process by documentation and
>> localization tools
>
> "In order to simplify the parsing process of documentation and
> localization tools" (perhaps ?)
>
> ---
>
> 3.7.1 .
>
>
>> Meanwhile, identified terms could be used for indexing that may
>> require some language specific information .For example, Japanese
>> words are sorted not by script characters, but by phonetic characters.
>> Therefore when a Japanese index item should be accompanied with a
>> phonetic string, called Yomigana.
>
> change to :
>
> "Meanwhile, identified terms could be used for indexing that may require
> some language specific information. For example, Japanese words are
> sorted not by script characters, but by phonetic characters. Therefore
> when a Japanese index item is created, it should be accompanied by a
> phonetic string, called Yomigana."
>
> - is that correct ?
>
> ---
>
> 3.8.1 Challenges :
>
>> Some reasons why this type of markup may require special attention:
>
> Maybe change to :
>
> "Here are some reasons why this type of markup may require special
> attention :"
>
> (again, not sure on this, it's a style thing, I guess)
>
>
> ---
>
> 3.9.1
>
>> Examples of issues are as followings:
>
> "Here are some examples of these type of issues:"
>
> ?
>
> ---
>
> 3.12.1
>
>> The mechanism should also allow to specify exceptions within
>> exceptions
>
> not sure that sounds right, but maybe I'm wrong. How about :
>
> "The mechanism should also allow one to specify exceptions within
> exceptions"
>
> or maybe
>
> "The mechanism should also allow for specification of  exceptions within
> exceptions"
>
> Similar (possible) problems with the next sentence :
>
>> ... it should allow to specify that <text> is to be translated, but
>> also that some occurrences of the <text> element (e.g. with an
>> attribute translate="no") are not to be translated.
>
> either "... it should allow one to specify"
>
> or
>
> "... it should allow for the specification of the fact that the <text>
> element is to be translated..."
>
>
> "The mechanism should be able to map existing elements that already
> carry implicitly or explicitly the translatability information."
>
> That sentence is fine, but it could be good to add a sentence
>
> "Here are some examples of this :"
>
> (a bullet list of examples follows that sentence)
>
>> The mechanism should provide a way to delimit a portion of the content
>> if such mechanism does not exists in the original vocabulary (so parts
>> of a content could be set to be translated or not).
>
> Perhaps replace with :
>
> "The mechanism should provide a way to delimit a portion of the content
> of the content if such a mechanism does not exist in the original
> vocabulary (so parts of the content could be marked as translatable or
> not)"
>
> ---
>
> 3.14.1
>
>> Any solution for one of the ITS requirements must take in account
>> these potential drawbacks and offer implementations that has a limited
>> impact in the original document and on the content models in the
>> original schema.
>
> perhaps change to :
>
> "Solutions for any of the ITS requirements must take into account these
> potential drawbacks and offer implementations that have limited impact
> on the original document and on the content models in the original
> schema."
>
>
>
>
> Okay, that's all I've got so far : hope these are useful.
>
> Yves, if you like, I can spend some time going through the Wiki,
> applying these changes myself to the items in there. That was something
> we discussed in todays call, I don't mind doing that, but it'd be nice
> to only have to fix these once ;-)
>
>  cheers,
>    tim
>

Received on Thursday, 21 July 2005 02:53:11 UTC