Implementation Experience Reports

OSLC RM Specification V1.0

Comments from Nicolas Kruk (IBM)

1. The documentation is too spread out. It'd be much easier to walk-through if we had a single document with a table of contents at the beginning rather than separate documents linked to from a single page.
2. Like sections should be grouped together. For example, when talking about the Rest APIs for requirements, it might be nice to have the Requirement Resource section there as well (with examples of the RDF). This way you don't have to jump back and forth during implementation.
3. General Vagueness. This was probably the most frustrating thing I found within the spec. As an implementer, it was tough to see exactly what I needed to implement based on what information was contained within the spec. This might be a more general issue related to the nature of OSLC (as you have said to me before, it is really up to us to decide how we implement certain things). Regardless of this, I think someone trying to consume the services provided through OSLC would have trouble understanding what all they could do if they only had the specification to go off of. I had to do quite a bit of hand holding for our SVT team to explain what the specification meant, and how they should be using the provided services in RRS 2.0.0.2.

An couple examples off the top of my head would be:
The REST API section

• In the Resource Model section, it says a "Put must update the resource with the supplied representation". But it does not go into detail about what this means (can you update name/description? add/remove links? etc).
• How backwards compatibility with previous OSLC Specifications is handled
• What error messages to expect

I think more scenario specific/practical examples might be helpful when talking about the OSLC Rest API so that consumers of the spec might have a better idea of what it is that they can do and how the interactions should look.

Comments from Brett G (IBM)

1. Requirements Management REST API - "Creation and Selection of Resources": I found this section confusing because I felt it too easily mixed non-UI and UI request types, without mentioning it was possible to get/update requirements without using a UI. Although reading, and rereading the page, clarified the situation I still felt that a section so prominantly displayed at the top of the page should have briefly mentioned the other request types.
2. Requirements Management REST API - "Security and Authentication": I found this section completely understated.
3. Requirements Management Service Description - "Service Discovery": It felt like the page jumped straight to the Service Discriptor. The page made sense after the reading the Service Provider Catalog link, but the order in which items and links were displayed made the first reading confusing.
4. Requirement Resource Definition: I thought the calm attributes in the example should have had a comment saying not part of the spec.
5. Requirement Resource Definition: The text before each rdf example containing request method and mime type was useful and I thought should be given before every example.
6. Requirement Resource Definition: I thought it should clearly state that the actual requirement content, and attributes, is left to the implementor to determie.
7. Delegated Resource Selection: I have had little exposure to this section so far, but I when I did read the pages I found the lines blurred between CALM and OSLC.
8. General: There were many examples showing rdf xml starting with rdf:<attribute name> when in reality rdf begings with <rdf:RDF..
9. General: It's often difficult to distinguish what is part of the spec and what is simply part of Jazz.
10. General: Etags were barely mentioned, and their purpose should have more prominence.
11. CALM: Finding the link rendering urls was extremely difficult.