Re: Array and Enum: Elements or Objects?

On 5/13/2011 12:25 PM, Gary Wright wrote:
> On May 13, 2011, at 11:45 AM, Hugh Sasse wrote:
>
>> Before you put this work in, I'd be inclined to ask: why is this a problem?
>> Are you seeing some possible form of confusion?  Just reading this paragraph
>> and not refreshing my memory of the docs, I'd tend to only distinguish between
>> elements and objects for things like Array#uniq where non-nil elements are
>> objects.  Otherwise, a variety of word use tends to make English flow better.
>> Why does English have another word for "walrus"?  Searching for
>> synonyms improve writing
>> produces a lot of relevant results.  Repetitive word choice seems to be
>> widely considered a fault.
> Consistency is very important in technical documentation. Using synonyms introduces ambiguity because it often isn't clear when the synonym is being used for no particular reason or when it is being used to indicate a distinctly different technical meaning.
>
> That being said, I think 'element' is an appropriate term to use when referring to an object stored in a container of some sort.  Using 'element' emphasizes the context.  So when referring to the container/containee role 'element' is appropriate but when the container/containee role is irrelevant, then 'object' is OK.  So I would encourage the use of both terms as long as the usage is consistent and not just reflective of different authors choices.
>

I'd agree with this viewpoint. Although "flow" has value, it's more 
important to be very accurate with word choice in technical 
documentation. Users expect and are very attentive to this. When a user 
sees the words object and element interchanged, they might be wondering 
why the term "object" was chosen in this instance but not the last one, 
not realizing that it was arbitrary. Because of this, they might 
misinterpret the documentation. It's hard to say how, but there are less 
surprises when you use consistent wording. In that sense, I don't think 
it's wise to use synonyms if the goal is simply to make the prose more 
interesting. If anything, I would say repetitive word choice is a good 
thing in technical documentation.

Of course this is all assuming that the usage is inconsistent. I haven't 
read all of the docs, but so long as the usage implies different 
contexts between "objects" and "elements", the usage is fine. If they 
really do mean "elements" when using objects, I'd support changing it. 
Just to be clear, I agree with Gary's explanation of the distinction 
between objects and "elements".

- Loren