Subject: [Sip] Format for review comments

From: Jonathan Rosenberg <[email-masked]>
Date: Mon, 11 Sep 2006 10:07:37 -0400

As folks can probably tell I've been going through the review comments 
on gruu this morning in preparation for the call today. I'd like to 
suggest a particular format for review comments which makes them much, 
much, much more useful.

There are two ways to specify your comment. I'll call them form 1 and 
form 2. Here are two examples on a fictitious document:

Form 1
------

Section 3.2.1, first para:

I disagree with this. Can we change the second sentence to say "header 
field parameter" instead?

Form 2:
-------

In Section 3.2.1:

 > The user agent then constructs the message. It does so by adding
 > a new header parameter to to the Contact header field.

I disagree with this. Can we change the second sentence to say "header 
field parameter" instead?

I'd like to STRONGLY encourage folks to use form 2 for comments. There 
are several reasons why:

1. When editing the xml source to account for the comments, I can find 
the offending text in form 2 in my text editor by doign incremental 
forward search for the quoted text. With form 1, since the xml source 
does not contain section numbers, I cannot search for section 3.2.1 
directly in the xml source. Instead, I would have to refer back to the 
final document, find that section, get the section header name, and then 
search for it in the xml source. Much slower.

2. When reading the comments in email, the comments are standalone in 
Form 2, but not Form 1. What I mean is, just by reading the mail, and 
not having the document in front of me, I can understand and comment on 
the comment. This makes it easier to respond quickly, as it reduces the 
burden required to properly parse the mail.

Thanks,
Jonathan R.

-- 
Jonathan D. Rosenberg, Ph.D.                   600 Lanidex Plaza
Cisco Fellow                                   Parsippany, NJ 07054-2711
Cisco Systems
[email-masked]                              FAX:   (973) 952-5050
http://www.jdrosen.net                         PHONE: (973) 952-5000
http://www.cisco.com

_______________________________________________
Sip mailing list  https://www1.ietf.org/mailman/listinfo/sip
This list is for NEW development of the core SIP Protocol
Use [email-masked] for questions on current sip
Use [email-masked] for new developments on the application of sip