Hello Ian, Your comments are extremely helpful. I'll wait a bit to see if anyone else has comments, and then put up a patch following your suggestions. thanks, brian On 4/3/17 12:53 PM, Ian Y. Choi wrote:
Hello Brian,
Thanks a lot for your sharing on thoughts on the spec.
Recently, Docs team added a paragraph for new contributors with English as a second language [1], but the perspective you are asking is something different from [1] I think.
For me, it seems that the paragraph does not clearly answer the question "How do you identify a producer or consumer?". In my opinion, the purpose of the detail description on this paragraph is to recall more thoughts with 'project ID' and 'user ID', and when I first see the title (question), I expect such as "There are several approaches which help users to identify a producer or consumer". "The first is ..., which .... It is useful when ... However, there can be a problem when...". "The other possible approach can be ... It really solves the problem in the first approach by ... However, there may be still some problems on ...". Then, I try to relate those two approaches I think into 'project ID' and 'user ID', but it is a little bit difficult for me to map into those two approaches with the details, advantages, and disadvantages.
This is just my thought from my brief review when I read the spec, and I hope that more I18n team members and also Docs team contributors help better description for readers with English as Second Language.
With many thanks,
/Ian
[1] https://docs.openstack.org/contributor-guide/non-native-english-speakers.htm...
Brian Rosmaita wrote on 4/3/2017 12:06 AM:
Hello i18n team,
There's a section of Glance documentation that's written in a colloquial american english style, but some contributors have expressed concern that this attempt to make a concept clear to non-technical american english readers may actually make it more difficult for ESL readers to understand. It would be awesome if a few ESL people would take a look and let us know what you think:
http://specs.openstack.org/openstack/glance-specs/specs/api/v2/sharing-image...
thanks, brian
_______________________________________________ OpenStack-I18n mailing list OpenStack-I18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n