[Techspec] FW: Gen-art review of draft-mankin-pub-req-08.txt

Copied to this list with Elwyn's permission.

Stephen Hayes

-----Original Message-----
From: Elwyn Davies [mailto:elwynd@dial.pipex.com]
Sent: Thursday, May 25, 2006 7:13 AM
To: Stephen Hayes (TX/EUS)
Cc: General Area Review Team; Mary Barnes; Allison Mankin
Subject: Re: Gen-art review of draft-mankin-pub-req-08.txt

Some thoughts on your responses in line.

Given that there is at least one matter of discussion and opinion, you 
are welcome to copy this to the techspec list or I can raise the issue 
separately.

/Elwyn

Stephen Hayes (TX/EUS) wrote:
> Hi Elwyn,
>
> Thanks for reviewing the document.  My responses are inline:
>
> Stephen
>
>   
>> -----Original Message-----
>> From: Elwyn Davies [mailto:elwynd@dial.pipex.com]
>> Sent: Tuesday, May 23, 2006 12:43 PM
>> To: General Area Review Team
>> Cc: Mary Barnes; Allison Mankin; Stephen Hayes (TX/EUS)
>> Subject: Gen-art review of draft-mankin-pub-req-08.txt
>>
>>
>> I am the assigned Gen-ART reviewer for
>> draft-mankin-pub-req-08.txt.  
>>
>> For background on Gen-ART, please see the FAQ at
>> <http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html>.
>>
>> Please resolve these comments along with any other
>> Last Call comments you may receive.
>>
>> Summary
>> =======
>> This is not quite ready for publication as Informational.  I 
>> have a number of issues with the document and a fair number 
>> of editorial points.
>>
>> Missing Items:
>> ==============
>> Interaction of Technical Publisher with 'IETF Family' 
>> approval processes:
>> The recently published draft-iab-rfc-editor-00 uses the 
>> concept of 'document streams' coming from various parts of 
>> the IETF Family 
>> (others have noted that a better term is needed) 
>> each with its own approval authority and process.  I think 
>> using this term in section 2 would be useful.
>>     
>
> It is true that section 2 describes only the IETF stream.  The actual requirements attempt to be a bit more generic in terms of who has approval authority (so that people developing requirements for non-IETF streams can reuse them), but probably needs to be vetted for an IESG bias.  I am happy with scoping the applicability to the IETF stream (with reuse encouraged by other streams).
>   
Generally I think this (the genrality) is successful.  s2 talks about 
documents 'processed' by the IETF/IESG, IAB and IRTF/IRSG.  Adding 
something like 'Each of these processes produces a document stream with 
it own approval process.' would cover the point.
>   
>> The 
>> requirements should include the need for the technical 
>> publisher to publish all documents sent to it by the approval 
>> authority for a stream (and the IAB is allowed to approve new 
>> streams - but there would have to be negotiation on capacity 
>> potentially).  Effectively this approval maps into an 
>> instruction to the technical publisher to perform the editing 
>> task (defines the pieces of work the technical publisher has 
>> to do). 
>>     
>
> Isn't this a meta-requirement or at least a higher order requirement?  If it will eventually be covered by draft-iab-rfc-editor, does it need to be covered here?
>   
I don't think so.  Basically this is a requirement on how the work of 
the tech publisher is started for each document.  We talk about 
'post-approval' but it is only implicit that this is what triggers the 
rest of the publication process.  It is the authorization for work to 
commence.
>   
>> There is a subsidiary issue here: If pre-approval 
>> review and editing is introduced, there will have to be some 
>> sort of formal request from the approving authority for the 
>> stream for the technical publisher to do a pre-approval 
>> review.  See the comments on s3.1 below.
>>     
>
> Section 5 talks about the need to adapt IETF processes to handle pre-approval review.  Is something more needed?
>   
>> RFC Editor presence at IETF meetings:
>> The current RFC Editor is expected to send representatives to 
>> IETF meetings.  This is not in the requirements - is this an 
>> oversight or deliberate?  See discussion on s3.19 and s3.21 below.
>>
>>     
>
> It was an oversight to omit the help-desk function.
>   
I think there possibly needs to be a discussion on the list of whether 
there is really a  requirement for personal presence - but given that it 
happens at the moment, the community needs to decide if it really 
needs/wants it.  Personally I have only consulted the RFC Editor 
presence once, but on the other hand it is nice to get some sort of idea 
of the face behind the editing 'blue pencil'.
>   
>> Minor Issues:
>> =============
>>
>> s1: RFC2850 and the RFC Editor charter which IAB is working 
>> on use the term 'Editorial Management'.  I think it would 
>> useful to explain that what is covered in this document is 
>> essentially that.
>>     
>
> It is certainly possible to indicate that these requirements cover "editoral management and publication" to tie back to 2850 and the charter.  However, to me the term "editoral management" is meaningless.
>   
Interesting!  I can actually do a course in Editorial Management here 
(should I have a mind to) so people in the industry have some view of 
what it means.  E.g.,  
www.train4publishing.co.uk/content/occstd/editorialm.doc.
>> s2: Is the policy on internationalization in fact covered by 
>> the statement in s3.10 that the IETf only publishes in English.
>>     
>
> I think the prose in a publication is expected to be in English. This does not preclude code points, names, etc. being in other languages.  Does this need to be clarified?
>   
On reflection probably not.
>> s2.1; s3.7, Req-POSTCORR-2: The term 'document shepherd' is 
>> (I believe) currently only defined in the expired draft 
>> draft-ietf-proto-shepherding-00.txt (Allison!!). It needs to 
>> be defined here.
>>
>>     
> This should probably be generalized to "appropriate techincal representative" or something similar.
>
>   
OK
>> s3.1, Req-PREEDIT-1: Pre-approval review is specified to 
>> occur prior to WG last call.  There are two issues here:
>> 1. Individual submissions (via AD) and some other documents 
>> (IAB) don't go through WG last call.
>>     
>
> Should probably be generalized to indicate that it is a review before the document is approved (which I guess is somewhat self-evident).  I think it was originally assumed that this tool would mainly be used on WG documents, but it is a symptom of the fact that we don't really know how we would use pre-approval review.
>
>   
Indeed so.  Being less definite and referring to the discussion we need 
to have (xref to s5.1) would be useful.  This could explicitly mention 
that we need to decide how this would be authorized also (covering the 
next point).
>> 2. Having the technical publisher do a pre-approval review 
>> requires the technical publisher to expend effort - since 
>> there will be a contractual arrangement in place, there needs 
>> to be authorization for this work to occur.  Which 
>> body/person is going to authorize this work? If the work was 
>> tied into IETF Last Call (or the Publication Requested state) 
>> this would be straightforward, but it is less so for 
>> documents at WG last call state, and we need to be careful 
>> that this doesn't slow things down by delaying WG last call. 
>> Also what happens if a document goes through multiple WG last 
>> calls as sometimes happens?  This issue is to some extent 
>> covered by the remark in the first bullet in s5, which 
>> implies that we have to work some of this out.
>>
>> s3.1 and s3.3:  Some of the wording here could be interpreted 
>> as covering technical review (notably document structure and 
>> proper use of keywords).  I think that we need to make it 
>> clear that for IETF documents we want technically aware 
>> editorial services, as distinct from independent submissions 
>> where technical review will probably be wanted.  To this end, 
>> having the Technical publisher recommend changes to document 
>> structure in post-approval editing is IMO a move too far, 
>> although it might be useful in pre-approval editing.  At the 
>> moment the requirements only explicitly call out review of 
>> document structure in Req-POSTEDIT-1 (although it is 
>> mentioned in the discussion of both pre- and post-editing).  
>> I would definitely not want the technical publisher second 
>> guessing the authors on correct use of RFC2119 keywords - 
>> leave that to gen-art ;-) .
>>
>>     
>
> A clarification can be added that technical review is not the role of the technical publisher (at least for the IETF stream.
>   
I think that there could also be some difference in emphasis between 
pre- and post-approval review: Advice on document structure pre-approval 
might well be useful, but is too late once it is approved.  IMO the 
wording as it stands reverses this bias.
>   
>> s3.4: Should there be some requirement on ensuring that 
>> references will not become outdated?  (s/are available/are 
>> and will continue to be available/?)
>>     
>
> Good point, most standards organizations have a requirement that references also be permanent.  Otherwise a reference to a draft would be ok.
>   
>> s3.7, Req-POSTCORR-3: I think 'unreasonable' is too vague.  I 
>> take it what is intended is something like '... that a change 
>> requested by an author constitutes an unapproved technical 
>> change rather than a purely editorial improvement.'
>>     
>
> It was vague to give the publisher a bit of flexibility.  It could also be when there are massive changes in Auth 48.
>   
How about

'... that a change 
requested by an author constitutes an unapproved technical 
change rather than a purely editorial improvement or represents a disproportionate editorial alteration at a late stage in the process.'

>> s3.9: I think it would be wise to cover the capability of 
>> taking input in XML or other markup language as well.
>>     
>
> Do you mean xml2rfc?  It was removed due to consensus at the last bof.
>   
Not necessarily xml2rfc explicitly.  I was trying to leave the door open 
for things other than plain old ascii.
>> s3.13, Req-EXCEPTIONS-1: Should this be 'at the direction of 
>> the *IESG*' rather than 'IETF'?
>>     
>
> It should probably be something like "authorized representatives of the IETF"
>
>   
>> s3.16: Given that the copyright/ownership of the archives 
>> resides with ISOC, it is not clear that having the permanent 
>> archive provided by the technical publisher is the right 
>> answer.  At the minimum, as part of the security 
>> arrangements, there should be a requirement to 'mirror' the 
>> archive at regular intervals in storage controlled by ISOC/IETF.
>>
>>     
> Is this something the RFC editor does now?  Backing it up to ISOC/IETF seems like a new requirement.
>
>   
I guess I am not certain where the master copies of RFCs and the 
associated sources physically reside., but it looks as if they currently 
live on servers at ISI (ftp.rfc-editor.org maps to the same IP address 
as www.isi.edu).  I believe that the IETF has generally been moving 
towards having all its information on machines that are controlled by 
the IETF/ISOC.  We want to be certain that there would be no issue with 
control of the archives in the event that the IETF Technical Publisher 
contract was moved between providers.
>   
>> s3.16, Req-INDEX-7:  I seriously disagree with this 
>> requirement.  The archive is a permanent archive.  Once 
>> published documents should not be destroyed: '.. remove all 
>> traces of the document'.  I think it should be replaced by a 
>> capability to withdraw a document but this should result in 
>> the document only remaining internally accessible.  There are 
>> potential legal issues if the document is totally destroyed.
>>
>>     
> This seems to be a damned if you do, damned if you don't issue.  This requirement was put in because some people were concerned that not being able to purge a document would expose the IETF (or ISOC) to legal action.
>   
There is a difference between removing public accessibility and totally 
purging the document.  I regret to say that this is a legal conundrum 
that I am not equipped to answer.  My guess would be that you might need 
both (one to deal with internal requests and the other to deal with some 
hypothetical court requirement).  I fear we may have to ask a lawyer.
>   
>> s3.17: The three requirements here carefully allow for 
>> searching for a document, getting the meta-information and 
>> integrating the searches with other IETF search tools.  
>> Unfortunately they aren't explicit that you can retrieve the 
>> document itself!!!
>>     
>
> ok.  "search" should probably be "search and retrieve"
>
>   
>> s3.19, Req-STATS-2; s3.21, Req-PUBHELP-2: I am noting this 
>> point here because it relates to how the reports/tutorials 
>> are delivered but it is a more general issue: At present 
>> representatives of the RFC Editor turn up IETF meetings in 
>> order to provide a help desk, deliver the report to the 
>> plenary, give tutorials and so on.  This is a significant 
>> expense for the RFC Editor organization. Historically the RFC 
>> Editor had (and, for some of the people involved, may still 
>> have) other reasons for turning up!  However we need to 
>> decide whether we are *requiring* the IETF Technical 
>> Publisher to show up in person at IETF meetings as this will 
>> be something which will have to be contractually specified.  
>> Reports could be delivered electronically without needing to 
>> have a rep in person at the meetings. Tutorials could be 
>> online or delivered by a volunteer proxy.
>>     
>
> I think providing a help desk should be a requirement.  ISOC can always tell us if they aren't willing to pay for it.
>
>   
>> s4.1: It should be made clear that the times mentioned in 
>> these requirements refer to the time waiting for the 
>> technical publisher to complete its tasks.  Both situations 
>> include (or may include) time waiting for feedback from 
>> authors which is outside the control of the technical 
>> publisher.  Alternatively the times can be redefined to 
>> eliminate the dependency on the authors' efficiency 
>> (especially in the pre-publication - s/b pre-approval? - review).
>>     
>
> These requirements were deliberately left vague since it only represents a general wish by the IETF.  Defining the metric more specifically was judged to be micro-managing the contractual terms.
>   
Sorry - I just reread it and the the actual reqirement (Req-TIMEFRAME-1) 
actually covers the situation.
>> s4.2, Req-THROUGHPUT-3: Are we imposing this requirement on 
>> the absolute value of the queue length or should it be 
>> measured relative to the input load?  A constraint on the 
>> absolute value is probably only feasible if the contract with 
>> the technical publisher is on a time and materials basis or 
>> there are strict limits on the number of documents/page 
>> volume expected to be processed per unit time.
>>     
>
> True, a caveat similar to what is in section 4.1 requirements should probably be added.
>
>   
>> Editorial:
>> ==========
>>
>> Global:
>> Capitalization of Section Headings (ss 3.1, 3.4, 3.5, 3.14, 
>> 3.16, 4.1, 4.3, 4.4)
>> Consistent usage needed for hyphenation: post approval -> 
>> post-approval (s3, item7; s3.3; s3.7; s4.3; s5, bullet 2)
>> post publication -> post-publication (s3.15; s5, bullet 6)
>> non author -> non-author (s4, item 3; s4.3)
>>
>> Consistent capitalisation of 'IETF Technical publisher' (some 
>> instances of IETF technical publisher).  ?Use 'IETF Technical 
>> Publisher' throughout?
>>
>> 4 instances where 'Technical editor' is used in place of 
>> 'Technical publisher' (s2, para 4; s3, para 2; s3.3, 
>> REQ-postedit-3/4) - I don't think this is deliberate.
>>
>> s1, para 1: s/An important output of the IETF, then, is 
>> published technical specifications./Therefore an important 
>> output of the IETF is published technical specifications./
>>
>> s2: As others have mentioned, a better term than 'IETF 
>> family' is desirable.  One possibility: s/by the IETF 
>> family/from within the IETF umbrella/
>>
>> s2.1: The figure contains a large number of unexpanded 
>> acronyms.  A terminology section would help (including RFC!).
>>
>> s3: The list labels run into the list item texts for higher numbers.
>>
>> s3.3: Unexpanded acronym: MIB
>>
>> s3.4, para 1: s/included/including/
>>
>> s3.5: Unexpanded acronyms: (MIB), ABNF, XML, ASN.1
>>
>> s3.6: s/populate protocol parameters/populate assigned 
>> numerical values of protocol parameters/
>>
>> s3.6, discussion: s/publication./publication process./
>>
>> s3.7: Add reference to s3.13 (exception handling) at end of 
>> Task description.
>>
>> s3.7, Req-POSTCORR-1: s/pre publication/pre-publication/
>>
>> s3.7, Req-POSTCORR-4: The wording of this section seems to be 
>> somewhat convoluted.  How about:
>>    The IETF Technical publisher should ensure that any 
>> post-publication 
>>    changes to a specification are applied to the source 
>> documents used 
>>    to create the published specification.
>>
>> s3.8, Discussion: 'these numbers' - suggest 'allocates RFC 
>> and other numbers (the current IETF stable identifiers) when 
>> the document is near...'
>>  
>> s3.9: The various abbreviations for document formats need to 
>> be defined and used consistently.
>>
>> s3.11: The Task Description and Discussion refer to 'status 
>> information' whereas the Req-STATUSTRK-1/2 refer to 'state 
>> information'.  This should be consistent.
>>
>> s4.1, Req-TIMEFRAMES-2: s/pre-publication/pre-approval/?
>>
>> s4.3: s/%/percentage/, s/percent/percentage/
>>
>>
>>     

_______________________________________________
Techspec mailing list
Techspec@ietf.org
https://www1.ietf.org/mailman/listinfo/techspec