Open Stack

Hi Brian,

I'm a native (non-US) English speaker, so I'm approaching this as a technical communicator, moreso than as an ESL speaker.

As Ian pointed out, the content is not well organised, and I think that's the main source of confusion, rather than the language used. I had to read the first two sentences a few times to understand what was being said, and it was mostly because of the strange construction. People don't expect to read passive, parenthetical statements in technical documents, so it comes as a surprise.

Additionally, there's a lot of words here for not much content. That makes it harder for everyone (regardless of native language) to understand, because it buries the important content in a bunch of filler words. Additionally, the content (according to the title) is about identifying producers and consumers, but the text uses producers, consumers, projects, users, and images, without being clear about what each thing is. For non-expert readers, there is no way for them to know if these terms are related, or possibly even different words for the same thing.

Here's my (very quick) rewrite of the first para, which might give you a good starting point (and that I'm sure many of the writers can improve further):

> Glance allows operators to decide whether images are owned by projects or whether
> they are owned by users. By default, images are owned by projects. This section will
> explain how to identify producers and consumers, in order to determine who should own
> which projects.

To give you an idea of the thought process in a rewrite like this, the first thing to determine is the most important information, and put that up first. In this case, that was in the third sentence (Glance lets you decide who owns images). This frames the problem. From there, you can go into more detail about what the chapter will cover (the solutions to the problem, hopefully!). Obviously, this is for an opening paragraph of a concept, but the general principle (find the most important thing) holds true for other content types as well.

HTH,
Lana

On 04/04/17 03:39, Brian Rosmaita wrote:
> 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.html
>>
>>
>> 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-api-v2.html#how-do-you-identify-a-producer-or-consumer
>>>
>>>
>>> thanks,
>>> brian
>>>
>>> _______________________________________________
>>> OpenStack-I18n mailing list
>>> OpenStack-I18n at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
>>
>>
> 
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170404/051ba0ac/attachment.sig>