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
