RE: Splitting the document?

I am happy to produce a stripped down copy of the versioning
document, call it "versioning core", and maintain both the "versioning core"
and "full versioning" documents.  From my perspective, this allows us to
separate the substantive question of what the semantics of the protocol
to be (for which I believe we have now reached consensus) from the more
political question of "what is in core".

Note: My agreement is based on the assumption that we will not delay
submission of the "full versioning" document for debate over "what should
go into core".  In particular, this means that we may end up submitting
the "full versioning protocol" to the IESG before we have reached consensus
on a "core versioning protocol".

Cheers,
Geoff

-----Original Message-----
From: Jim Whitehead [mailto:ejw@cse.ucsc.edu]
Sent: Friday, December 01, 2000 5:33 PM
To: ietf-dav-versioning
Subject: Splitting the document?


Juergen Reuter writes:
> I am not very happy with the current structure of the document which
> divides all features into core WebDAV versioning and optional WebDAV
> versioning.  Currently, the core part is getting smaller and smaller,
> while the optional part continuously grows.  The problem I see is that
> server implementors will either implement the core part only, or, in
> practice, they will have to implement also the full optional part

This is an excellent segue into an issue I wanted to bring up.  The
packaging of the protocol specification into one or more documents has been
considered several times by the design team.

There are two primary options that have been discussed:

1) Status-quo: describe the entire protocol, both core and advanced, in one
document.

Advantages:
* Possible increase in number of full server implementations (core +
advanced) of protocol
* Reduced document overhead for boilerplate text, definitions,
introductions, etc.
* Increased consistency, since all text is within a single document

Disadvantages:
* A single document is larger, and there is a perception that large protocol
specifications are complex.
* A single document hides the inherent simplicity of the core versioning
features.  The simple core may be viewed as complex by its inclusion in a
long document.
* Possible decrease in implementations of core features in authoring clients
(due to perceived complexity)
* Possible decrease in implementations of core versioning in document
management servers.

2) Divide the specification into two documents, one for Core, one for
Advanced.

Advantages:
* Possible increase in number of authoring client implementations, due to
the easily seen simplicity of the Core.
* Possible increase in number of document management servers that implement
Core versioning
* It is likely Core versioning could be sent for IESG approval before the
Advanced document was entirely completed.
* If interoperability problems are discovered in the Advanced features, they
could be fixed without impacting the specification of Core features. This
could lead to increased confidence in the Core features by implementors, and
hence greater early adoption of Core features.

Disadvantages:
* Possible decrease in number of server implementations of Advanced
features.
* Possible decrease in number of client implementations of Advanced
features.
* Possible increase in inter-document inconsistency.
* Repetition of defintions of terms, boilerplate text, etc.
* Need for a document roadmap explaining subdivision of documents.


I have long favored keeping the document together, as a whole (option #1).
However, I am starting to lean towards subdividing the document (option #2).
My rationale is as follows:

* Due to the relatively large number of optional Advanced features, there is
significantly increased risk of interoperability problems in the Advanced
portion of the specification. Since there has not yet been an
interoperability demonstration of an Advanced client working against
multiple Advanced servers, there is currently no evidence that can be used
to effectively assess this risk.  As a result, it seems prudent to examine
what would happen in a worst-case scenario where interoperability problems
in Advanced features lead to a recycle at Proposed Standard.

Re-issuing an RFC at Proposed can happen when there need to be such
substantial modifications to a document that they transcend the "minor
changes" threshold for going to Draft Standard.  Alternately, it could be
that two interoperable implementations of each feature cannot be
demonstrated. If this were to happen to the DeltaV protocol, and the
protocol were specified in one document, it would require modifying the
entire document, Core plus Advanced.  This would have the effect of adding
substantial implementation risk even to vendors implementing just the Core
features.  This risk might lead to implementation being postponed, and a
much slower adoption of the protocol. In contrast, if Core were kept in a
separate document, and Advanced features needed to be revised, it is likely
they would not impact the Core, and hence would not increase its
implementation risk.

* A small Core document would be easier to "sell".  It would be much easier
to convince implementors that a small Core versioning document is compact,
and easy to implement, than Core in a large document.  Even though Core only
takes a small portion of the current document, an implementor still needs to
read through the entire document, for sections like i18n, security, etc., to
ensure nothing has been missed.  For a small document, this work has already
been performed, by the act of creating a smaller document.

* The downside risk of separating the documents appears to be small.  The
major downside risks of separating the documents appears to be that there
will be few client or server implementations of the Advanced features, and
hence the Advanced features will be marginalized.  While there have not been
any product announcements that I am aware of, it seems reasonable to assume
that the participation of top engineering talent from several significant CM
vendors in this effort implies a willingness to implement all of the
standard, Core and Advanced.  Additionally, the Subversion open source
project is currently implementing a very full-featured CM client based on
DeltaV.  So, I am not concerned about implementations of the Advanced
features -- I think this will happen.

I am more concerned about authoring tools implementing the standard,
primarily due to concerns about the complexity of the protocol, based on
Core being packaged with Advanced features.  A smaller Core document would
allay some of these concerns, since authoring tools will primary just use
the Core features.

But, this said, I also recognize that development orgaizations interested in
implementing the protocol will perform a thorough engineering analysis
anyway, and will quickly see through superficial issues such as document
length.  Furthermore, in the annals of engineering specifications, the
current DeltaV spec. is nowhere near the upper end of the scale for
complexity, and length.  Far more complex interoperability specifications
have been implemented over time.

As a result, while I find myself somewhat in support of splitting the
current document, I am not 100% convinced.  I would appreciate hearing other
views on the matter.

- Jim

Received on Sunday, 3 December 2000 22:10:10 UTC