Subject: Re: [apps-discuss] AppsDir review of draft-ietf-sipclf-format-05

From: Gonzalo Salgueiro <[email-masked]>
Date: Wed, 8 Feb 2012 19:52:16 -0500

Hi Claudio - 

Thanks for the thorough review.

See inline comments.

On Jan 19, 2012, at 5:21 AM, Claudio Allocchio wrote:

> 
> I have been selected as the Applications Area Directorate reviewer for this draft (for background on appsdir, please see http://trac.tools.ietf.org/area/app/trac/wiki/ApplicationsAreaDirectorate).
> 
> Please resolve these comments along with any other Last Call comments you may receive. Please wait for direction from your document shepherd or AD before posting a new version of the draft.
> 
> Document: draft-ietf-sipclf-format-05
> Title: Format for the Session Initiation Protocol (SIP) Common Log Format
>       (CLF)
> Reviewer: Claudio Allocchio
> Review Date: 2012-01-18
> IETF Last Call Date: unknown
> IESG Telechat Date: unknown
> 
> NOTE: is there is an IESG telechat which I'm missing, just copy this messae to iesg ML!
> 
> Summary:
> 
> This draft is ready for publication as a Proposed Standard RFC; it just needs one consideration about a minor issue about an external reference, and fixing some Nits.

This is great news. Thanks.
> 
> Major Issues:
> 
> NONE
> 
> Minor Issues:
> 
> just one !
> 
> * Section "3. Document Conventions"
> 
> The authors have decided "For the sake of clarity and completeness" to quote a full section of RFC4475 into this document. However there were quite long discussions in the Apps Dir in other reviews if this quoting practice is appropriate or not, because it can lead to discrepacies, when the quoted document is updated or obsoleted, resuing in confusion for the readers who just trust the quoted text without checking the state of the referenced document. I would suggest, as in the other cases, NOT to quote the external text, but to use an explicit external reference only, urging the reader to check that "for the sake of clarity".

I agree with the position but in this particular case I'm of the mind that removing that text and referencing the RFC diminishes the effectiveness of that section. It is my preference to leave the quoted text (which is very short) embedded in this document as it is critical to understanding the notation used throughout the document.
> 
> Nits:
> 
> * Section "Copyright Notice"
> 
> change the year to 2012.

Will do this.
> 
> * Section "3. Document Conventions"
> 
> remember to change "formatting rules for Internet-Drafts" into "formatting rules for RFCs" when published.

Great point. I'll proactively beat the RFC Editor to this.
> 
> * Section "4. Format"
> 
> I do understand that it probably does not fit into the I-D formatting line lenghts, but... maybe an attempt to add aside the SIP CLF record depicted in Figure 1 the grouping described as
> 
>                                 <IndexPointers>
>                                 <MandatoryFields>
>                                 <OptionalFields>
> 
> in the figure 1 itself (on the left?) may help in reading the distinction, and maybe may even not require to repeat portions of the figure itself later in the I-D, like in figure 3, figure 4 and figure 5. It is really a nit and just a suggestion. Not really important.
> 
> What I am suggesting:
> 
>       +----------------------------------+
>      /|                                  |
>     / |                                  |
>   P   |                                  |
>   o   |                                  |
> I i   |                                  |
> n n   |                                  |
> d t   |                                  |
> e e   |                                  |
> x r   |                                  |
>   s   |                                  |
>    \  |                                  |
>      \|                                  |
>       +----------------------------------+
>      /|                                  |
>     / |                                  |
> M     |                                  |
> a F   |                                  |
> n i   |                                  |
> d e   |                                  |
> a l   |                                  |
> t d   |                                  |
> o s   |                                  |
> r     |                                  |
> y  \  |                                  |
>      \|                                  |
>       +----------------------------------+
>      /|                                  |
>     / |                                  |
> O     |                                  |
> p F   |                                  |
> t i   |                                  |
> i e   |                                  |
> o l   |                                  |
> n d   |                                  |
> a s   |                                  |
> l     |                                  |
>    \  |                                  |
>      \|                                  |
>       +----------------------------------+
> 

This is something that we have discussed and have not found an elegant solution for. 
While there are maintenance risks it was thought to be very valuable to display the 
pertinent portion of the complete CLF within the section where that was discussed. 
I'll do my best to ensure that they are all copied over properly from Figure 1.

> * Section "5. Example SIP CLF Record"
> 
> Remember to change "Due to internet-draft conventions" into "Due to RFC conventions" when published (and also "to format it for an RFC" later on...).

Indeed.
> 
> * From the DataTracker ID Nits check tool (References Nits):
> 
>  == Unused Reference: 'RFC5612' is defined on line 984, but no explicit
>     reference was found in the text
> 
>  ** Downref: Normative reference to an Informational draft:
>     draft-ietf-sipclf-problem-statement (ref.
>     'I-D.ietf-sipclf-problem-statement')
> 
> Comment: the document shepard is aware and has a solution for these nits. Just apply it.

Absolutely.

Thanks,

Gonzalo

> 
> ------------------------------------------------------------------------------
> Claudio Allocchio             G   A   R   R          [email-masked]
>                        Senior Technical Officer
> tel: +39 040 3758523      Italian Academic and       G=Claudio; S=Allocchio;
> fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;
> 
>           PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Claudio Allocchio <[email-masked]>
Date: Thu, 9 Feb 2012 08:47:05 +0100 (CET)

Hello all!

>> The authors have decided "For the sake of clarity and completeness" to 
>> quote a full section of RFC4475 into this document. However there were 
>> quite long discussions in the Apps Dir in other reviews if this quoting 
>> practice is appropriate or not, because it can lead to discrepacies, 
>> when the quoted document is updated or obsoleted, resuing in confusion 
>> for the readers who just trust the quoted text without checking the 
>> state of the referenced document. I would suggest, as in the other 
>> cases, NOT to quote the external text, but to use an explicit external 
>> reference only, urging the reader to check that "for the sake of 
>> clarity".
>
> I agree with the position but in this particular case I'm of the mind 
> that removing that text and referencing the RFC diminishes the 
> effectiveness of that section. It is my preference to leave the quoted 
> text (which is very short) embedded in this document as it is critical 
> to understanding the notation used throughout the document.

maybe a possible compromise is to quote the text, as is now, but to add a 
small note which reminds the reader to check the update/obsoletes status 
of RFC4475? ;-)

>> * Section "4. Format"
>>
> This is something that we have discussed and have not found an elegant 
> solution for. While there are maintenance risks it was thought to be 
> very valuable to display the pertinent portion of the complete CLF 
> within the section where that was discussed. I'll do my best to ensure 
> that they are all copied over properly from Figure 1.

as I said, it is a Nit... thanks for taking some time in thinking about 
it.

have a nice day!

---

From: Gonzalo Salgueiro <[email-masked]>
Date: Thu, 9 Feb 2012 09:44:11 -0500

Hi Claudio - 

On Feb 9, 2012, at 2:47 AM, Claudio Allocchio wrote:

> maybe a possible compromise is to quote the text, as is now, but to add a small note which reminds the reader to check the update/obsoletes status of RFC4475? ;-)

I could add that but bear in mind that I only care about the quoted text dealing with formatting rules from RFC4475 and nothing else. So whether it gets updated or obsoleted is irrelevant in this case. In fact, if it gets updated and it affects the formatting guidelines I quoted then I don't want to reference it at all since it is no longer useful or significant to this draft.
> 
>>> * Section "4. Format"
>>> 
>> This is something that we have discussed and have not found an elegant solution for. While there are maintenance risks it was thought to be very valuable to display the pertinent portion of the complete CLF within the section where that was discussed. I'll do my best to ensure that they are all copied over properly from Figure 1.
> 
> as I said, it is a Nit... thanks for taking some time in thinking about it.

Thanks to you for your careful review.

Warm Regards,

Gonzalo