Subject: [Simple] Comments on draft-ietf-simple-partial-notify-02

From: Dean Willis <[email-masked]>
Date: Wed, 28 Apr 2004 11:34:55 -0500

I have a couple of non-fundamental observations on the partial notify draft.

Obs 1: Overall style challenge: Overuse of requirements language in 
descriptive passages.

People tend to use RFC 2119 requirements language when describing how 
things work, rather than when describing actual requirements.

This is subtle, and many (most?) people don't understand the difference. 
You can probably get away with ignoring me here, but it might be worth 
thinking about. It has big implications on the establishment of formal 
compatibility documents -- when people say "MUST" everytime they mean 
"does", it makes the real requirements hard to identify.

As an example, the text in this draft:

4.4  Presence agent generation of partial notifications

   If the presence agent decides to send notifications according to this
   specification that include a presence document, the presence agent
   MUST build a presence document according to the PIDF extension for
   Partial Presence [2] and MUST set the Content-Type header field to
   the value 'application/pidf-partial+xml'.

   Tuple ids are used to match tuples across subsequent notifications.
   Presence agent MUST use the same tuple ids for tuples which are
   identical between subsequent notifications and MUST allocate
   different tuple ids for tuples which are different from previously
   sent tuples. Presence agents MUST keep tuple ids consistent until the
   next full state presence documentis delivered. The decision on
   whether tuple ids are the same or different is left up to PA's local
   policy.

Would perhaps be more clearly written as:

4.4  Presence agent generation of partial notifications

   If the presence agent decides to send partial notifications in response
   to this subscription, it constructs the partial presence documents
   as specified in the PIDF extension for Partial Presence [2]. As required 
   by [2], the presence agent sets the Content-Type header field of each 
   partial presence document to the value 'application/pidf-partial+xml'.

   Further requirements apply to partial presence documents, as follow:

   Tuple ids are used by clients to match tuples across subsequent 
   notifications. For this matching to succeed, the Presence Agent MUST 
   not vary the tuple ids for tuples that have not changed since they
   were previously sent on this subscription and and MUST allocate different 
   tuple ids for tuples that are different from previously sent tuples. 
   Presence agents MUST keep tuple ids consistent until the next full-state 
   presence document has been sent and acknowledged. The decision on whether 
   tuple ids are the same or different in the next full-state presence document
   is left up to PA's local policy.

In the first paragraph, we are describing how the presence agent does 
something by way of example. In the second and third, we are stating 
requirements that vary from the general way of building presence 
documents, i.e, "new requirements". I've also polished the English slightly.

Obs 2: Section 5:
... The PA accepts the subscription and, based on the "q" parameter 
value, selects to send ...

The phrase "selects to send" is a bit awkward as English construction. 
"Selects" has the connotation of choosing from a menu, which is not 
quite what we want here.
"Decides to send" might work better. Whatever you choose should align 
with the wording you've decided to use in the (elsewhere discussed) 
discussion of how the server decided whether or not it was going to 
provide partial notifications for this subscription.

Obs 3: Use of domain names in examples:

Some examples use domain names in "somewhere.com". This probably needs 
to be changed to a domain reserved in RFC 2606. Perhaps ".test"?

After all, "somewhere.com" is a real domain: 
    Somewhere.Com, LLC
    25 Forest Circle
    Winchester, MA 01890
     US

--
Dean

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple