Re: Complexity and Core Considerations

   From: "Jim Whitehead" <ejw@cse.ucsc.edu>

   > The first question is just an editorial question.  I would prefer to
   > keep the versioning protocol as one document -- after all, when the
   > first paragraph of the introductions says:
   >
   >   "An implementor that is only interested in core versioning should read
   >    Section I (Introduction), Section II (Core Versioning), and Section
   >    15 (Report Option)."
   >
   > is a reader really all that likely to be confused?

   Yes, because in order to implement core, you also need to read, understand,
   and subset the information in the security considerations, i18n, IANA
   considerations, references, as well as understand and implement the error
   reporting extensions listed in the appendix, so you can properly report
   errors from VERSION-CONTROL.  And these are just the ones I can list from
   memory.

First, I agree that the "core implementor should read ..." should be
fixed to say "core implementor should not read the optional sections
numbered 3-14", since I agree that a core implementor should read the
security etc. sections.

But let's look at Jim's key argument that a core reader would have to
subset the information in these sections.  I just reread the security,
i18n, IANA considerations, and references sections, and the only part
that does not apply to core versioning is one sentence in the i18n
section that refers to labels.  So this means that these sections
would have to be replicated in full in two documents (I don't think
the IESG would allow us ommitting these sections in either of the
documents).

This means that a diligent reader of both documents (and the majority
of respondents so far have indicated they will be doing at least one
option) would have to read all these sections twice, only to discover
that there is only one additional sentence in one of those sections.
We could warn them by adding a prefix to each section saying
"note: this is a copy of the same section in the core versioning
document", but that is only slightly less unappealing.

   Plus, a core-only document would have a shorter introduction, and a
   shorter definitions section, making it ever so easier to
   understand.  A core-only document would also appear much less
   intimidating, since, if printed double-sided, you could make a
   working paper airplane out the stack of papers. :-)

Only a paragraph or two could be ommitted from the introduction
(the semantics of the options appear in the options sections, not
in the introduction).  Also the optional definitions section is clearly
marked as such, and I believe serves as a vital point of reference
for the majority of the readers who will care about at least one
of the options. 

As for the paper-airplane argument, a 40 page double sided document
will probably be the smallest versioning-related document that a
versioning implementor has ever enountered (:-).

Cheers,
Geoff

Received on Monday, 5 February 2001 11:00:00 UTC