Subject: [Techspec] RE: Comments on draft-mankin-pub-req-05.txt

From: "Stephen Hayes (TX/EUS)" <[email-masked]>
Date: Tue, 21 Mar 2006 21:28:06 -0600

Thanks for taking the time to review the draft.  See my responses below:

Stephen

> -----Original Message-----
> From: Elwyn Davies [mailto:[email-masked]]
> Sent: Tuesday, March 21, 2006 3:10 PM
> To: [email-masked]
> Cc: [email-masked]; Stephen Hayes (TX/EUS)
> Subject: Comments on draft-mankin-pub-req-05.txt
> 
> 
> Some comments on draft-mankin-pub-req-05.txt:
> 
> s3.7, second para:
> >
> > Discussion: IETF allows minor technical corrects during the
> >
> >    publication process.  This should ideally be a rare 
> occurrence, but
> >
> >    as publication times increase, the number of minor technical 
> > improvements increases.
> >
> (editoral aside: s/corrects/corrections/)
> The phrase 'but as publication times increase' reads like a 
> criticism of 
> throughput , and whilst we may have a problem with this, the 
> issue here 
> is 'in the abstract'.  I suggest s/but as publication times 
> increase.. 
> increases/but should time from initial approval to final publication 
> increase, the number of minor technical improvements that might be 
> incorporated is likely to increase correspondingly./ - 
> Certainly we need 
> to keep this time down: the s4.1 proposal seems reasonable and should 
> limit the opportunity for thinking of cunning new tweaks to sneak in 
> under the wire.

This certainly wasn't intended to imply a need for longer publication times.  I will reword this requirement (although I may not use exactly the suggested words)

> 
> s3.7:
> >
> > Current Req-POSTCORR-2 - The IETF technical publisher should only
> >
> >       allow post approval technical changes which have been 
> approved by
> >
> >       the IESG.
> >
> 
> > Potential Req-POSTCORR-3 - The IETF technical publisher should
> >
> >       have the discretion to reject post-approval corrections as too
> >
> >       late in the process and propose that it be handled as errata.
> >
> This requires a certain level of technical savvy and judgment in the 
> technical editors to ensure that they can tell the difference between 
> editorial and technical so as they don't have the wool pulled 
> over their 
> eyes by authors.  This is a significant requirement for any 
> organisation 
> that might bid for this work.

This is an open issue I will raise at the techspec BOF.

> 
> s3.7, last para: the implication is that there might be 
> multiple source 
> documents - what these are is not really discussed until 3.9: 
> it might 
> be good to either put 3.9 before 3.7 or move the discussion of what 
> constitutes source documents to at or before  this point.

We are somewhat vague in the draft about what the source documents are because it's probably not possible to cover all cases.  I fear that having a discussion of multiple source documents in the early sections will just detract from the main point of the earlier requirements.  If the auxilary source documents are code or formal languages, the technical publisher might be able to validate them but I wouldn't expect the technical publisher to edit them.  So in my view, the primary requirement for dealing with multiple source documents doesn't really come until section 3.16 (Potential Req-INDEX-5).  However, I can add some early text to indicate that the possiblity of multiple source documents does exist.

> 
> s3.9, Discussion: I was under the impression that at present the RFC 
> Editor would accept postscript and pdf as well as ascii but 
> does the RFC 
> Editor actually do conversions?  In the recent past (last few hundred 
> RFCs) anything other than txt is rare (about 3 pdfs I could 
> find).  In 
> general terms the RFC Editor needs more than ascii input to 
> create pdf 
> or postscript output and this certainly doesn't happen by default.
> 
The only conversion referred to here is creating a postscript and pdf output of an ascii document.  No additional conversion is implied.

> s3.16, Potential Req-INDEX-5: Also need to archive any 
> necessary tools 
> and know what version of tools was used to create 
> corresponding output.

Is this really needed?  We are not actually developing products.  If both source files and output are archived, isn't it sufficient to indicate that one of them is normative?

> 
> s3.17: Should be an additional requirement to give access to archived 
> source to (?appropriately authorized) people for the purposes 
> of making 
> derived works (like new versions) or getting MIB sources etc. 
>  This may 
> result in an extra item in s5.

I had assumed that all source documents were accessible.  Is there a reason to restrict access to a subset of the files?

> 
> s3.19: I think that we should explicitly require that the editorial 
> style guide is published.

I thought the IETF was trying to stay away from an explicit style guide.  I had not explicitly assumed that a style guide exists in the requirements.  In my experience having a published style guide starts you down the road to fairly bureaucratic processing of documents and only really starts becoming useful when you shift away from ascii or xml generated drafts.  
> 
> s4.1, Potential Req-TIMEFRAMES-2: 'Documents held up due to 
> references 
> or...': I don't see why this should be a cause for delay of early 
> allocation of an identifier. '...or due to a
>       protocol action should be excluded from this 
> statistic.': I am not 
> sure which action this might refer to.  I think this whole 
> sentence is 
> probably a cut and paste error.

This sentence isn't a cut and paste error.  It was taken out and then added back in.  The reason it was put back was that if there is an expected delay in publication (due to dangling references or other reasons) then you don't want to allocate the id early.  While a reference delay doesn't prevent you from supplying an early permanent ID, you can't ensure that the final published document will be available in a timely manner.

> 
> s4.1/s4.2: The metrics in these two sections define the 
> overall scale of 
> the operation which the IETF is requiring/expecting the technical 
> publisher to perform. I think we could usefully add an extra section 
> indicating how we would task the technical publisher (and 
> hence how the 
> IETf would be charged).  Depending on whether we are looking 
> for a Time 
> and Materials contract (the IETF sends documents, the 
> contractor agrees 
> to process them according an SLA based on s4.1 and charges per unit 
> processed) or we agree a Fixed Price contract based on a 
> throughput per 
> unit time as measured in s4.2, and any additional documents 
> have to wait 
> (or are done on a special basis - expedited handling again!).

Although I agree that the contact conditions could effect the quality of service provided, it seems to me to be out of scope of this document.  The actual contract conditions will be determined by the contract negotiations.
> 
> s6: Potential Req-DOCCONVERT-2 in s3.9 would require 
> additional work in 
> the IETF to complete and maintain xml2rfc  if it is adopted.
> 
Yes. Given the usage of xml2rfc, isn't this the defacto case now?

> Editorial:
> s3.5, last para (Current Req-FORMALVAL-1): s/xml/XML/

ok, Thanks

_______________________________________________
Techspec mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/techspec

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 22 Mar 2006 09:55:51 -0600

At 9:28 PM -0600 3/21/06, Stephen Hayes (TX/EUS) wrote:
>I thought the IETF was trying to stay away from an explicit style guide.

That would be a Bad Thing. Having a style guide helps reduce the 
number of edits that a conscientious author will face in Auth48. It 
is very disconcerting to have, for example, to have the title of your 
RFC-to-be changed just before it is published based on style 
considerations that you didn't know about.

>I had not explicitly assumed that a style guide exists in the 
>requirements.  In my experience having a published style guide 
>starts you down the road to fairly bureaucratic processing of 
>documents and only really starts becoming useful when you shift away 
>from ascii or xml generated drafts.

Going down that road is not a requirement. Many of us who have 
written books for multiple publishers have seen a range of how 
bureaucratic the copyediting and formatting of documents based on 
house style guides.

--Paul Hoffman, Director
--VPN Consortium

---

From: Elwyn Davies <[email-masked]>
Date: Wed, 22 Mar 2006 16:10:04 -0600

> Thanks for taking the time to review the draft.  See my responses below:
:-)
This mostly seems ok.. responses inline.
/elwyn
> This certainly wasn't intended to imply a need for longer publication times.  I will reword this requirement (although I may not use exactly the suggested words)
Fine.
> This is an open issue I will raise at the techspec BOF.
this has its own thread....
> We are somewhat vague in the draft about what the source documents are because it's probably not possible to cover all cases.  I fear that having a discussion of multiple source documents in the ea…
That would probably be fne.
> The only conversion referred to here is creating a postscript and pdf output of an ascii document.  No additional conversion is implied.
Just that as far as I know it is not currently done!
> Is this really needed?  We are not actually developing products.  If both source files and output are archived, isn't it sufficient to indicate that one of them is normative?
This has been discussed elsewhere.  The problem is that if we use 
xml2rfc, we need to be sure that it is strictly backwards compatible and 
produces the same output for the old output forever.. otherwise the 
output is not reproducible.  This has some effect on exactly what your 
'index'/archive has to maintain - if you can't guarantee to reproduce 
output then the output MUST be stored securely as well as the  source.  
At the moment,as I understand it, the RFC Editor keeps the nroff as the 
main archive.. but that may not be the real state of play.
> I had assumed that all source documents were accessible.  Is there a reason to restrict access to a subset of the files?
At the moment the nroff source is not immediately available on line AFAICS.
> I thought the IETF was trying to stay away from an explicit style guide.  I had not explicitly assumed that a style guide exists in the requirements.  In my experience having a published style guid…
See separate thread.
> This sentence isn't a cut and paste error.  It was taken out and then added back in.  The reason it was put back was that if there is an expected delay in publication (due to dangling references or…
OK.  I hadn't been following in detail.
> Although I agree that the contact conditions could effect the quality of service provided, it seems to me to be out of scope of this document.  The actual contract conditions will be determined by…
We'll take this elsewhere!
> Yes. Given the usage of xml2rfc, isn't this the defacto case now?
xml2rfc is still experimental... it would have to be a bit more 
'official' if it becomes the archive format.