[Oslc-recon] Comments on Recon spec

[Steve K Speicher]

These comments are on the February 21th revision of the spec 
http://open-services.net/wiki/reconciliation/OSLC-Reconciliation-Specification-Version-2.0/revision/2170/

1) Please remove/update the red warning text in the front to be like how 
PerfMon and Auto used (not just removing red text).  It is very clear from 
previous version that this is the first version, don't need to reiterate.
Namely:
"NOTE: This version of the specification has version 2.0 to indicate that 
it is an OSLC Core 2.0 compliant specification. This specification is the 
initial version of an OSLC Reconciliation specification."

2) #Introduction
The term "artifact" and other general terminology really don't help me 
know what this spec is about.  It would be helpful to include some 
specific samples/examples of how it might: computers, IT resources, etc

3) #Namespaces 1
Namespaces should be hyperlinked so one can click on it to see the actual 
vocabulary document.

4) #Namespaces 2
This statement seems like it does not help me (the reader) and just a 
general statement about how the WG works.  If there were other 
namespaces...I would expect it just to say it uses the other ones here, 
perhaps list them and then move on.
"The OSLC Reconciliation workgroup MAY also re-use vocabulary terms from 
other namespaces as needed after agreement on domain scenarios."
change to:
"The namespaces that represent re-used vocabulary terms are:
  - http://open-services.net/ns/asset#Asset
..."
as a possibility.

5) #ResourceFormats
Just an observation (I know many other specs doe this as well) I wonder 
why we say anything about atom+xml anymore, do you really expect it?  It 
would seem like we should instead have the media type for JSON or more 
JSON considerations.

So I'd strike the atom+xml bullet and "Atom Syndication Format XML", 
unless you have some hint of a need.

6) #ComputerSystem / Additional Requirements
6a) 2nd bullet, crtv_hostid should be crtv:hostid  (replace the '_' with 
':').  vmid missing namespace prefix too?

6b) Are bullets 1 & 2 just telling me I need a crtv:hostid ?  what the 
positive and negative of vmid? Likewise for bullets 3&4, do I need vmid? 
Some additional explanation/samples may help here (directly or 
referenced).

7) #Database & IPAddress & Path & ServiceInstance & ServerAccessPoint & 
SoftwareModule / Addtional Reqs

It says "Multiple bullets may be satisfied" but there is only 1 bullet.

8) #ServerAccessPoint crtv:portNumber
The reference is vague to the definition (IETF and IANA), there a better 
direct reference to a definition.

9) All resource definitions / classes
It might be helpful to hyperlink the "Type URI"'s to the vocabulary 
definition.

10) #ServiceProviderResource

oslc:serviceProvider is a MUST....should be a MAY

11) #Authors and Contact Information
merge with "Contributors" section as the current section is empty, see 
Automation with example.

12) Patent non-assert link/doc?


Thanks,
Steve Speicher
IBM Rational Software
OSLC - Lifecycle integration inspired by the web -> 
http://open-services.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-recon_open-services.net/attachments/20130222/462da9ec/attachment-0003.html>