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

From: [email-masked]
Date: Mon, 3 May 2004 12:30:44 +0300

> 
> 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.

Right, I think I understand your concern. I will try to polish use of
RFC2119 requirements language in the next version.

> 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.

Right, I will change that and try to align it with the rest of the text.

> 
> 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

Yes, this will be changed to example.com.

Thanks
- Mikko

> --
> Dean

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

---

From: [email-masked]
Date: Mon, 3 May 2004 12:30:44 +0300

Thanks
- Mikko