Review comments on White Paper

[William Cox <wtcox@CoxSoftwareArchitects.com>]

I'm putting these in one email; many issues are global to the document. The document betrays a lack of maturity, and is not fully reviewable in its current form. I look forward to a detailed review of WD02.

(0) The document is a good start, but needs significant work. The TC should review the draft, outline, and details at the next TC meeting. I'm sure that there are issues not caught because of the hard-to-review format. Full discussion and guidance for the technical editor is indicated.

(1) The document is not easily reviewable -- there are no line numbers in the PDF, and only the even page numbers are shown. The sections are not numbered. It is an imposition on reviewers to give them a 25 page document in such a form.

(2) My review will be more brief than it would have been with proper markers to point to. Substantial portions cannot be reviewed in their current form; the next draft with line numbers will help.

(3) Footer on page 3 (before the odd page numbers disappeared) is "Title of White Paper". Fix,.

(4) The introduction, last para, says "EERP applies service discovery, composition, simulation, and optimization techniques..." overstates. Which part of which specs that are CD02 apply those things?  This introduction is very misleading.

(5) Page 5 ""will be on enablers for optimization..." - this is future tense for something explaining current work.

(6) Next para - "such how" is wrong.

(7) Page 6 top (See why line numbers are required?) Where is BPMN in the current specs? I think this overreaches.

(8) Page 7 first para change part of text to read "...have been approved by the SOA-EERP TC as Committee Drafts."

(9) What is the source of the diagrams? If you used XML Spy you should acknowledge.

(10) Through page 13 seems to be a recitation of the schemas. Should start with the conceptual framework and motivate the schemas and specs, not the other way around. A white paper should tell you why you should care, then go (as necessary) into the details.

(11) There is a suggestion on pages 14-15 that the TC has done some of this work (no line numbers). It needs to be very clear at each step that this is NOT in the current work of the TC, so readers won't look for the details. Wording thoughout e.g. "The EERP will have the following messages exchange" reinforces that mid-impression.

(12) Diagram (no number) on page ?15 - conventionally the requester is on the left, not on the right. This arrangement is counter-intuitive.

(13) Numerous issues with text throughout. As WD01, this clearly needs more work to be a positive exposure of the SOA-EERP work to the world.

(14) I did not review the examples in detail due to lack of line numbers. Next WD needs line numbers so it can be reviewed adequately.

(15) References are WRONG. There is no such thing as a normative reference in a whitepaper. Correct. Delete RF2119 reference as well.

(16) Revision history says this is Rev 00, but it's described elsewhere as "WD 01"

(17) Number the figures so they can be easily referenced.

Thanks!

bill
--

William Cox
Email: wtcox@CoxSoftwareArchitects.com
Web: http://www.CoxSoftwareArchitects.com
+1 862 485 3696 mobile
+1 908 277 3460 fax

eerp_sy@changfeng.org.cn wrote:

380-2200973891823311@M2W032.mail2web.com" type="cite">

The document named EERP Model and UseCase WhitePaper PDF
(EERP-Model-UseCase-WhitePaper.pdf) has been submitted at
www.oasis-open.org/committees/download.php/33289/EERP-Model-UseCase-WhitePap
er.pdf 

The relationships among three specifications and the intended use cases are
documented. 

This issue can be closed. 


Original Message:
-----------------
From: William Cox wtcox@CoxSoftwareArchitects.com
Date: Wed, 24 Jun 2009 19:27:36 -0400
To: eerp_sy@changfeng.org.cn, soa-eerp@lists.oasis-open.org
Subject: Re: [soa-eerp] I048: Use Case Document and additional justification


I think this should be addressed by creating a folder for Use Cases and 
Models as a placeholder, and starting with several of the contributions. 
Closing this issue is OK, need to open new one for that new document.

bill cox
--
*William Cox*
Email: wtcox@CoxSoftwareArchitects.com 
<mailto:wtcox@CoxSoftwareArchitects.com>
Web: http://www.CoxSoftwareArchitects.com
+1 862 485 3696 mobile
+1 908 277 3460 fax


eerp_sy@changfeng.org.cn wrote:
  

Same as Issue I052, it is proposed to change the protocol of this issue
    

to: 
  

Protocol: examples

Artifact: example 

Type: design 

That is the issue to be addressed in the Example document. No spec changes
are required on this issue for now. 



Szu Chang 

Original Message:
-----------------
From: eerp_sy@changfeng.org.cn eerp_sy@changfeng.org.cn
Date: Sun, 21 Jun 2009 15:39:09 -0400
To: wtcox@coxsoftwarearchitects.com, soa-eerp@lists.oasis-open.org
Subject: [soa-eerp] I048: Use Case Document and additional justification


Issue # I048

The protocol change to "examples" 

Original Message:
-----------------
From: William Cox wtcox@CoxSoftwareArchitects.com
Date: Sat, 20 Jun 2009 22:43:19 -0400
To: soa-eerp@lists.oasis-open.org
Subject: [soa-eerp] NEW Issue: Use Case Document and additional
justification


PLEASE DO NOT REPLY TO THIS EMAIL OR START A DISCUSSION THREAD UNTIL THE 
ISSUE IS ASSIGNED A NUMBER.

The issues coordinators will notify the list when that has occurred.

Protocol: bqos rating sla

Artifact: spec

Type: design

Title: Use Case Document and additional justification

Description:

This issue applies to
BusinessQualityOfService-v1.0-spec-wd04.pdf
BusinessRating-v1.0-spec-wd05.pdf
BusinessServiceLevelAgreement-v1.0-spec-wd04.pdf

On reading all three specifications together, it's not clear what the 
relationships are and the intended use cases.

A use case document would help described the intended usage and 
approach, and clarify issues I've separately raised..  In particular, 
the justification for the mechanisms in the three current 
specifications, and a large integrated example, would be very useful.

This issue may be addressed after the current Committee Draft in 
progress is completed, but would help the public review be more 
effective if addressed before Public Review.

Related issues:

Proposed Resolution:

Write a use case and relationships/background document. This could be a 
non-normative white paper, or could coordinate with the information from 
the non-normative sections (to be written) for the three specifications. 
I think that a single use case and relationships document would be best.


bill cox
--
*William Cox*
Email: wtcox@CoxSoftwareArchitects.com 
<mailto:wtcox@CoxSoftwareArchitects.com>
Web: http://www.CoxSoftwareArchitects.com
+1 862 485 3696 mobile
+1 908 277 3460 fax

    

 

--------------------------------------------------------------------
mail2web LIVE – Free email based on Microsoft® Exchange technology -
http://link.mail2web.com/LIVE