--On Monday, 06 February, 2006 14:50 -0800 Eric Rescorla
<[EMAIL PROTECTED]> wrote:
> Paul Hoffman <[EMAIL PROTECTED]> wrote:
>
>> 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.
>
> That's exactly the question I think is appropriate to be
> considering.
While I agree with your reasoning about editing consistency for
document versions, I think the question / recommendation is too
narrow.
My impression is that the RFC Editor adopted (incrementally and
perhaps not explicitly) a policy/procedural change around six
years ago. Prior to that time, the style rule was for both
submissions and output was, approximately "look at other RFCs
that seem to be similar to this one in content, weighted by more
recent ones, and do something similar". Stylistic changes were
generally made in editing only when they were necessary for
clarity, when the submitted style was just wrong, or to improve
stylistic consistency within the document itself. The more
recent trend has been to make significant stylistic changes
during editing, apparently to enforce conformance with a style
manual that no one has really seen (see below).
While there is a plausible alternative (again, see below), I
believe that _any_ purely stylistic editing that goes beyond the
traditional (significantly pre 1999) practice is a bad idea.
The comments about diff tools applies equally well to I-D -> RFC
changes as it does to revised RFCs. Increasing the number of
changes made in editing increases the risk of errors slipping in
undetected (e.g., we discovered last week that a substantive
error had been introduced into a key procedural document,
apparently because the copy editor, in trying to transform "a,
b, and c" constructions to "a, b and c" ones, repositioned a
comma in a qualifying phrase. Because of the list changes, he
authors' eyes glazed over in AUTH48 and stopped looking at comma
changes. And, of course, making changes that do not need to be
made consumes resources --both in the editing process and by the
authors in checking, etc., -- that could presumably be used in
other ways.
"Below": On the other hand, there is another way to accomplish
the same goal. The IETF community should make a choice and then
be careful about what is wished for. The traditional,
permissive, style conventions actually pose a problem. In my
experience, if one hires professional copy editors without a
history with the document series, their first question is "to
which style manual are we editing?". If the answer is "we don't
have one", then each such editor will tend to apply his or her
own rules. The types of changes Eric and Spencer identify are
then almost inevitable. So the other alternative is to charge
the editor with creating a formal, publishable, style manual for
technical documents and then to insist that everyone conform to
it.
The main disadvantages of doing so are that creating and
agreeing on one would also consume resources, getting technical
specification authors to conform to a particular style manual
shifts resources from the specification editing process to
volunteers, which is probably not a shift we want to make, and
the flexibility inherent in our traditional approach is often A
Good Thing. On the other hand, a single, specific style is
much easier to permit and enforce with generic document markup
and similar tools than the more flexible tradition.
Again, one should be careful about one wishes for -- some years
ago, at least one publisher decided to solve the "a, b [,] and
c" problem by insisting on SGML markup of the character of
<valuelist> a b c </valuelist>
and then treating the presentation of the construction as a
formatting matter. While that actually has some significant
advantages, such as permitting "a, b, c, d, e, and f" to be
turned into a bulleted list if some conditions are met, it can
get extremely tedious for the person creating the document and
doing the generic markup.
john
_______________________________________________
Techspec mailing list
[email protected]
https://www1.ietf.org/mailman/listinfo/techspec
