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 protected]
https://www1.ietf.org/mailman/listinfo/gen-art
