[UCR] preliminary review of UCR document

I am sending out this preliminary review for the purposes of discussion 
this morning.
Full document to follow later.
============================================================================================

This is a preliminary review, only partly done. More to come later.

Review of  "RIF Use Cases and Requirements," draft of February, 2007, 
available at 
http://www.w3.org/2005/rules/wg/wiki/FrontPage?action=AttachFile&do=get&target=EditorsWD-rif-ucr-20070201.html 
.


I. Preliminary Remarks:

1) Differences between this draft and working draft of 10 July 2007:

The differences between this document and the latest working draft include 
(listed in order):
--- An added paragraph in the introduction motivating the use cases
--- A section, at the end of each use case, listing some requirements 
which the use case motivates
--- A significant modification and rewriting of Use Case 5, Managing 
Inter-Organizational Business Policies and Practices
--- The addition of Section 2.11, Analysis of Usage Scenarios and Their 
Processing Models, demonstrating in a step-by-step manner how the RIF 
might be used in a particular use case.
--- An added paragraph on the critical success factor of interoperability
--- The addition of a subsection on general requirements, which include 
some requirements listed in previous versions of this document.
--- A concluding section.

2) Focus of the review:

This review will focus on the modifications and additions made since the 
last draft but will also comment on material present in the previous 
draft.

Most comments address substantive technical issues and/or issues of 
clarity. Purely stylistic remarks (typos, grammatical errors, suggestions 
for rephrasing) are pointed out in the final section of the review.

II. The Review

Overall, the document is well organized and reads smoothly.

Nevertheless, improvements could be made in the following aspects/areas:

1) :Problems with discussion of requirements:

A) Not comprehensive.

For example, the requirement of round-tripping is not mentioned. Even if 
full round-tripping  is not feasible, there should be some discussion of 
this important requirement.

B)  Related to A: There should be some sense of what makes us believe that 
this set of requirements is in some way comprehensive. Is there any way to 
show completeness, in some sense? (See point D, below.)

C) The discussion at the end of each use case linking use cases to 
requirements is wildly uneven. (I am one of the offenders here.) In 
particular, it is often the case that a requirement is listed for one use 
case, but it seems equally (or more) applicable to other use cases. At the 
very least, as a stop-gap, it should be noted in the introduction that 
this is the case. But more generally, there needs to be a reconsideration 
of all use-cases and requirements.

D) In general, this all seems a bit ungrounded. I would think one of the 
points of the use cases is having concrete examples with which to work. I 
would guess that working on these examples will point out difficulties 
that we'll run into while doing RIF, and that these difficulties will lead 
to certain requirements. None of this has been done, and as a result, I 
have no confidence that the set of requirements as thus far listed is in 
any way comprehesive. 





2) Focus/clarity: 

The writing is sometimes a bit muddled, and it's hard to tell what the 
focus of a particular section is. For example, the discussion in the 
introduction of the use cases isn't sufficiently clear. For example, what 
does it mean to say "these use cases also represent a kind of committment 
[sic]" ? A commitment to what? And by whom?

Also muddy:
---the new paragraph on use cases: "Additionally, the use cases illustrate 
some of the principal ways in which RIF can provide benefits" 

--- use case 5 is very unclear

--- Section 2.11 is not too clear. It's a good section to have, but needs 
to be improved.

--- the conclusion is unfocused and not written as well as it could be.







3) Formatting issues:

1. The sample (natural language) rules in the use cases do not print out 
well and are difficult to read on the screen. On the screen, one is forced 
to scroll all the way to the right. When one prints the file out, the 
natural language rules are cut-off, making the use case very difficult to 
understand. This had been fixed in the previous working draft, but has 
re-emerged as  a problem.

2. The font for the use cases is much smaller than in previous drafts and 
consequently harder to read.


4) Stylistic Issues:

There are a variety of stylistic problems which should be cleaned up:
1. Spelling mistakes: e.g., "committment" instead of "commitment." 
(Introduction, paragraph 3)
2. Grammar mistakes, including
  a) run-on sentences, e.g.
3. Awkward usages, e.g., "obsoleted" instead of "made obsolete."
4. Inconsistency in writing styles throughout the document. Inconsistency 
in presentation of use cases.