comments on the current draft

[Tsutomu Kamimura <EBB0CMB@jp.ibm.com>]

I quickly went through the current draft
and created my comments as follows.

----------------------------------------------------------------------------------------------

• Chapters 4 and 5 are the main body of the spec for the standard. I agree with Arthur in that the content in these chapters is in fair shape. My main comment here is the order in which resource definitions are presented in Chapter 5. Now that we have Figure 7 that describes hierarchical view of resources, it would make it more natural if resource definitions follow that hierarchy. Also, each container defined in Figure 7 is also a resource. Isn't it necessary to include all these container definitions in Chapter 5? I see that 4.4 defines containers. But as discussed at the last call, some containers such as IssueCollection Container takes additional parameters such as the list of Issue resources when it creates an instance of IssueCollection.
• ManagedItem and ManagedItem Collection do not have Containers. Isn't it helpful to explain how these resources are used? They correspond to abstract classes of the domain model, so their use is to be included by other resources, and no need for containers.
• Chapter 1 is incomplete. Are we going to complete 1.3, 1.4 and 1.5?
• As Arthur pointed out, 1.2 and the first part of Chapter 2 are duplicated.
• Figure 2 needs more explanation. What is Adapter? What does each doted arrow mean? What about green arrow? Why is green arrow for B2 go to Dmain Model while one for B1 go to Resource Definition?
• On Chapter 3, main action is to make this chapter as "Informative" or "Non-normative" as discussed at the last call. If not, I suggest we consult OSLC MS SC to get their support to include domain model as part of the standard.
• Name of a class is sometimes inconsistent.  Lower case is used in some times (such as artifact, plan, report,..)  and Upper case is used in other times.
• Examples of 3.2 describe only a subset of a whole model. For example, Project, a top-level resource, is not there. It is because that is obvious in many cases. But, it may be helpful to mention it there.
• I did not check all the resources, but saw some differences with Chapter 3. For example, Artifact in Chapter 3 has three links while that in Chapter 4 has two links. One in Chapter 4 has a link producedFor has one to many relationship. So, one in Chapter 4 can point to multiple ScopeItem while one in Chapter 4 cannot. Why is this difference?
• Chapter 6 and 7 need improvement. In paragraph 6.2, "The deployment pattern 'B' and 'C' is deliberative one". What does this mean?
• Figure 9 needs more explanation. What do you mean by (Web Service)? The following paragraph says "The provider runs web service which has REST architecture". What does it mean?
• Section 6.3.2 needs to explain more on terminology.  For example, what do you mean by "register ProjectID"? Do you mean to store resource URI to some place? Also, it uses DB without explaining it.  Same for PM, PM-A, PM-S, and so on. We used these in our discussion, but they have to explained first in the document.
• I saw a number of grammatical errors in 6.3.2. We should use some tool to detect these.
• Chapter 7 is too long and too detailed. Do we need this level of content for the standard spec? Can we extract only very essential part? It says that this chapter explains detailed flow of each use case described in Chapter 6. But I see that Chapter 6 and 7 are not connected well in number of aspects. For example, it is only for deployment pattern A. Also, Chapter 6 says that project initiation is not included there, but Chapter 7 starts its description at that phase.  Also, Chapter 7 uses Excel Adapter extensively, but since it is not a part of the spec and Excel Adapter is not described anywhere in this document, explanation is needed.
• I think Chapters 6 and 7 can be better as appendix. In fact, Chapter 7 refers to the content of previous chapter as it is in Appendix.

-----------------------------------------------------------------------------------------------------------------------


Tsutomu Kamimura

Consultant, Tokyo Lab Strategy