Re: "Outline" algorithm (document length and complexity)

The document is currently over 930 pages when printed
"letter" size. The first complaint I get from implementors
wanting to review the specification is that it is
unreviewable: too long, to complex, too difficult to
review individual sections, too difficult to find
the definition of terms, or where things are used.

The difficulty of reviewing the content is likely the
most serious threat to the quality of the document -- it defeats
the open standards process to have long documents without
sufficient reviewers.  The longer the document -- and
the more it churns during the standards development process --
the fewer the number of individuals there are who will have
the time and energy to review the specification and be able
to track its changes. 

My calling out this section was part of the review of the
use of pseudo-code algorithmic specifications. It is
well known that it is difficult to verify whether an
algorithm produces expected results, and even more 
difficult to determine whether two algorithms produce
equivalent results, which someone wishing to test
conformance would have to do.  Expressing normative
requirements in terms of sets of constraints which the
results of the implementation must satisfy is far
preferable from the point of view of validation,
testing, and document review.

If we are concerned about whether the document can be
reviewed, then an algorithmic normative section that
is also lengthy is even more egregious. Being
"precise" in this way may be counter-productive,
if no one is really capable of evaluating the
precision.

The fact that OTHER specifications might need some
formal definition of an algorithm which can be used
in HTML -- but which has no use within HTML itself --
is not a good justification for retaining this
section within the document.

While there may be other applications which want a 
common definition of "outline", those other applications
have their own requirements, ways of determining
conformance, and constraints which this working group
is not in a position to review. There is no way of
determining conformance, for example. There are no
requirements for "outline" against which this particular
outline algorithm can be reviewed.

In any case, if the "outline" specification has
no application within HTML itself, then it can
be put in a separate document and processed
independently.

Regards,

Larry
-- 
http://larry.masinter.net

Received on Tuesday, 26 May 2009 15:22:14 UTC