RE: [icom] Article

[Eric Chan <eric.s.chan@oracle.com>]

I consistently use the plural form in phrases "attached markers," "category applications," "tag applications," etc., instead of modifying the property names, like "attachedMarkers," "categoryApplications," "tagApplications," etc. The property names are consistently expressed in singular form in UML and RDF model and augmented with cardinality specification. The text describes the properties and cardinality instead of repeating the property names. This is a consistent style throughout the article. Not every reader switches back and forth between text and figures when they read. So describing the properties in the text reduce "context switching." I am trying to make it easier for readers.

Thanks,
Eric


-----Original Message-----
From: Patrick Durusau [mailto:patrick@durusau.net] 
Sent: Thursday, January 20, 2011 4:59 AM
To: Eric Chan
Cc: icom
Subject: RE: [icom] Article

Eric,

On Wed, 2011-01-19 at 14:51 -0800, Eric Chan wrote:
> Hello Patrick,
> 

<snip>


To illustrate the problem with the text as written:

>  
> 
> They have the diagram, do we need to repeat the listing? 
> 
>  
> 
> There is a subtle difference, the plural word “attached Markers”
> combine the name “attachedMarker” with “cardinality 0..*” information.
> 
>  

That is exactly the sort of "subtle difference" that we need to avoid at
all cost.

That is obvious to you as the *designer* of the ontology but I don't
think you can find anyone at Oracle who would agree that is obvious on a
first, second or even third reading of the text. 

Why not be clear, explicit and non-repetitive (or at least consistent if
you are going to be repetitive?)? 

This is not a question of "technical people" or "technical content." 

Writing that is meant to communicate, clearly, is not subtle or clever. 

It is one of the reasons why standards and even materials to explain
standards are so boring. ;-) 

I know this is how you want to explain what you have done. That isn't
the question. The question is how to best explain it to others. Not the
same question. 

Yes?

Hope you are at the start of a great day!

Patrick


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php