Subject: [Techspec] Editing consistency

From: Eric Rescorla <[email-masked]>
Date: Mon, 06 Feb 2006 10:30:51 -0800

I'm currently working on the Auth-48 version of RFC 4346 (TLS 1.1),
which is a very light revision to TLS 1.0 (RFC 2246). During this
review, I noticed that RFC Ed had made a number of stylistic
edits to text that was in RFC 2246. For instance, all heads have
been changed from "text style" to "title style". E.g.,

From:
	3. Goals of this document

To:
	3. Goals of This Document

A bunch of copy-edit changes have also been made.

I don't want to start an argument here about the desirability of this
type of change in general (though think that's a discussion worth having
at some point) but I think it's worth discussing the relative importance
of different kinds of consistency, in particular:

* Stylistic consistency across documents published contemporaneously
* Stylistic consistency across time, especially for documents that
  are clearly related.

In particular, it seems to me that there are some clear drawbacks to
making this kind of stylistic change in successive versions of the same
document, both in terms of effort consumed by editors and authors and
in terms of the effort required to figure out "what changed" by those
using automated difference tools. It's worth noting that although
capitalization differences are easy to suppress, there are other 
stylistic changes that are less so.

What do people think about this?

-Ekr

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

---

From: "Spencer Dawkins" <[email-masked]>
Date: Mon, 6 Feb 2006 15:52:49 -0600

Well, speaking only for myself:

- I am very excited by the introduction of copy editors earlier in the 
process, because I really see how that can improve things for IETF 
standards.

- I am not excited by stylistic editing late in the process, because I don't 
see how that really improves things for IETF standards.

- If there is any chance that editing resources that could be doing copy 
editing early in the process are doing stylistic editing late in the 
process, I'm very un-excited about that.

Re "consistency": if you look at RFC 793 and any recent RFC side-by-side, 
you can tell the difference from across the room - I'm sorry, but you can. I 
don't think that's bad. Given that we won't have consistency across all 
time, I don't know why consistency across all documents published in a given 
month or year matters.

... especially if it means that the changes need to be made repeatedly 
across updated documents, and especially stylistic changes make it more 
difficult to spot what "really" changed between versions. The current diff 
tools do everything except send up flares to help you spot differences - why 
would we make it harder to find "real" differences?

If we care, we should have stylistic stuff coming out of the working group 
correctly, and I can't see how that's going to happen unless a program can 
enforce a style (probably by formatting text to conform to it).

I am not a genius of this stuff, but, since you asked...

Thanks,

Spencer

---

From: Paul Hoffman <[email-masked]>
Date: Mon, 6 Feb 2006 14:29:44 -0800

At 3:52 PM -0600 2/6/06, Spencer Dawkins wrote:
>Given that we won't have consistency across all time, I don't know 
>why consistency across all documents published in a given month or 
>year matters.

I don't think that was Eric's point. He showed that a *revised RFC* 
had stylistic changes such as capitalization in the headings and 
copy-editing changes (for example, changing "that" for "which", or 
changing "since" to "because"). He pointed out a real mechanical 
problem: it is hard to use a diff-style tool to determine the 
relevant changes.

Thus, there may be a Techspec requirement here that the publisher not 
make purely stylistic changes on RFC revisions.

--Paul Hoffman, Director
--VPN Consortium

---

From: Eric Rescorla <[email-masked]>
Date: Mon, 06 Feb 2006 14:50:49 -0800

Paul Hoffman <[email-masked]> wrote:

> problem: it is hard to use a diff-style tool to determine the relevant
> changes.
> 

That's exactly the question I think is appropriate to be considering.

-Ekr