Requirements for IETF Technical Publication Service
draft-mankin-pub-req-11

PreEdit-1

I think the requirement for pre-approval editing is probably stated wrong. We have not decided we are going to use this and would not want any contract pricing to be based on this. It might be better to phrase it more along the lines of, if the IETF decided to use pre-approval editing, it should be possible for the editor to provide .....

PostEdit-2

I find be confused on what a "document shepherd" is in this case. (I have same problem other places this term is used in this document). Would be nice to clarify this term. 

RefVal-1

On the expected remain available part, I think this is only needed for normative references.


FormalVal-1 

I find this very difficult to do for topics I am an expert in. I suspect it will be very difficult for the technical editor will be able check a files is a valid X.509 cert, or check that a file is a valid GML file that include definitions from multiple namespaces. I guess it depends on the level of checking we are thinking will happen. If we could clarify what sort of level of checking we are thinking of that would be better. It seems this might be better done by the WG.  


DocConvert-2

This requirement does not make sense to me. The editor should accept these files and do what with them? 

Expedite-1

When one stream expedites some document, it slows down other streams. Do we want any other stream to be able to slow down IESG stream?

Stats-3 and Stats-4

This seems lacking definition on what we want and very expensive to track. I think we should carefully consider what we would be willing to pay to get this? 

PubHelp-1 and PubHelp-2

I like the idea of this but it is not clear to me that it should be the publisher doing this. 

TimeFrames-2 

Given we have consensus to even do pre approval editing, I think saying that we agree it should be done 10 days might be a bit strong. It is not clear if you mean the average is under 10 days or it is always under 10 days. Having it this sort sounds fairly unrealistic to me. Given the burst nature of when documents get done at IETF, if we have enough resources to turn this around in 10 days most the time, they resource will be idle a large percentage of the year.

Section 1., paragraph 3:

>    The intention of this document is to clarify the IETF's consensus on
>    its requirements for its technical publication service.  This
>    document is not a discussion of how well the RFC Editor fulfils those
>    requirements.

  Nit: s/the RFC Editor/the RFC Edidor, who is the current IETF
  technical publisher, /


Section 2., paragraph 2:

>    This draft specifically addresses those documents published by the
>    IETF technical standards process.  In all cases, the requirements
>    have been written in generic terms, so that they may be used to
>    express the requirements of other RFC streams, elsewhere.

  s/RFC streams/streams of technical specifications/ - since that's what
  the preceding paragraphs claim?


Section 2.1., paragraph 5:

>                Figure 1: Stages of a Working Group Document

  Nit: Figure 1 breaks between pages.


Section 3.3., paragraph 15:

>    o  Req-POSTEDIT-3 - The IETF technical publisher should exercise
>       restraint in making stylistic changes that introduce a substantial
>       review load but only provides incremental increase in the clarity
>       of the specification.  Specific guidelines on the types of changes
>       allowed may be further specified, but ultimately restraint in
>       editing must be imposed by the IETF technical publisher.  Changes
>       for stylistic consistency should be done only when there are major
>       problems with the quality of the document.

  It may make sense for the IETF technical publisher to provide some
  style and grammar recommendations to the author community to minimize
  the need for such stylistic changes. (Oh, I see you have this below;
  nevermind.)


Section 3.11., paragraph 4:

>    o  Req-STATUSTRK-1 - The IETF technical publisher should make state
>       information publicly available for each document in the
>       publication process.

  Would be good if the the IETF technical publisher made this state
  (also) available through a documented interface, for tools
  development.


Section 3.16., paragraph 3:

>    o  Req-INDEX-1 - The IETF technical publisher should maintain the
>       index of all IETF published documents.

  Would be good if the the IETF technical publisher made this index
  (also) available through a documented interface, for tools
  development.


Section 4.1., paragraph 4:

>    o  Goal-TIMEFRAMES-1 - The consensus of the IETF community is that
>       an average publication time of under a month is desirable.  It is
>       understood that in some cases there will be delays outside of the
>       publisher's control. The actual performance targets and metrics
>       are expected to be determined as part of the contract negotiation
>       process.

  Can we maybe phrase these performance expectations a bit more
  precisely in terms of O(pages)?

Section 1: Missing Reference for what ISDs are.

Section 3.1: Missing reference for the early copy editing experiment.

Section 3.2: 
   Discussion: This is not required.  A final approved version is 
   available as a draft.  If publication can take more than 6 months, it 
   may be necessary to take measures to ensure the draft version remains 
   available. 

I think that the formulation in the above is a bit strange considering that we do have a mechanism in place that don't kill of draft if the process takes more than 6 month.

The document needs to expand acronyms when first used. Most, such as "RFC", "IPR", and "BCP" the reader is very likely to know. Some like "IANA", "ETSI", etc most readers will know, but some might not. At least one "ISDs" I couldn't figure out.

  Section 3.15 is an area where improvement is really needed.  First,
  errata need to be published in a more timely manner.  Second, errata
  need to be much easier to locate.

  Section 4 should include a discussion of timely errata publication.

  Section 7 should also talk about integrity of the index.

Cleared my discuss in favor of Lisa's.

In 3.2, the document says:

 If publication can take more than 6 months, it 
   may be necessary to take measures to ensure the draft version remains 
   available. 

It might be useful to clarify that the actor taking these measure is not necessarily the technical publisher.

In 3.5, the document says:

   Discussion: The RFC Editor validates sections of a document 
   containing MIBs, Augmented Backus Naur Form (ABNF), eXtensible Markup 
   Language (XML), Abstract Syntax Notation One (ASN.1) and possibly 
   other formal languages. 

 Req-FORMALVAL-1 - The IETF technical publisher should validate 
      sections of documents containing formal languages.  In particular 
      ASN.1, ABNF, and XML should be verified using appropriate tools. 

It may be useful to clarify that "verification" for XML is for well-formed XML, rather than validation against a DTD; validation often has the second meaning for XML.  The text above the formal requirement makes this a bit ambiguous.

In 3.6, the document uses both the term "insert" and "populate" for assigned protocol parameters.  I personally found populate less confusing, as "insert" sounded more like IANA's registry action. YMMV.

In 3.9, the document says:

Discussion: Currently, the RFC Editor accepts input as an ascii text 
   file (supplemented by xml if available)

I believe the RFC Editor also still accepts nroff.

Nit:

Post-publication Corrections: Appropriate processes must be 
      defined with the IETF to ensure that errata is appropriately 
      vetted and authorized. 

"errata" is plural.