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

From: Elwyn Davies <[email-masked]>
Date: Tue, 23 May 2006 18:43:13 +0100

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

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.

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.

s2: Is the policy on internationalization in fact covered by the statement in s3.10 that the IETf only publishes in English.

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.

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

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/?)

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

s3.9: I think it would be wise to cover the capability of taking input in XML or other markup language as well.

s3.13, Req-EXCEPTIONS-1: Should this be 'at the direction of the *IESG*' rather than '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.

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.

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

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.

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

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

_______________________________________________
Gen-art mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/gen-art