oslc-promcode message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: comments on the current draft
- From: Tsutomu Kamimura <EBB0CMB@jp.ibm.com>
- To: PROMCODE TC <oslc-promcode@lists.oasis-open.org>
- Date: Thu, 14 May 2015 12:11:14 +0900
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]