[Bug 28016] New: Vague references – $N versus 5000 x $N

https://www.w3.org/Bugs/Public/show_bug.cgi?id=28016

            Bug ID: 28016
           Summary: Vague references – $N versus 5000 x $N
           Product: XPath / XQuery / XSLT
           Version: Candidate Recommendation
          Hardware: PC
                OS: Linux
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Functions and Operators 3.1
          Assignee: mike@saxonica.com
          Reporter: patrick@durusau.net
        QA Contact: public-qt-comments@w3.org

A duplicate of 28015 but on a different component. I was unable to choose
multiple components for a single commment. 

By way of illustration:

[Definition: An atomic value is a value in the value space of an atomic type,
as defined in [XML Schema 1.0] or [XML Schema 1.1].] [Definition: A node is an
instance of one of the node kinds defined in [XQuery and XPath Data Model (XDM)
3.1].

In the example, you and I both know somewhere in XML Schema 1.0 and XML Schema
1.1 that the “value space of the atomic type” is defined. The same is true for
nodes and XQuery and XPath Data Model (XDM) 3.1. But where? The authors of
these specifications could insert that information at a cost of $N.

What is the cost of not inserting that information in the current drafts? I
estimate the number of people interested in reading these drafts to be 5,000.
So each of those person will have to find the same information omitted from
these specifications, which is a cost of 5,000 x $N. In terms of convenience to
readers and reducing their costs of reading these specifications, references to
exact locations in other materials are a necessity.

Vague references are also problematic in terms of users finding the correct
reference. The citation above, [XML Schema 1.0] for “value space of an atomic
type,” refers to all three parts of XML Schema 1.0.

Part 1, at 3.14.1 (non-normative) The Simple Type Definition Schema Component,
has the only reference to “atomic type.”

Part 2, actually has “0” hits for “atomic type.” True enough, “2.5.1.1 Atomic
datatypes” is likely the intended reference but that isn’t what the
specification says to look for.

Bottom line is that any external reference needs to include in the inline
citation the precise internal reference in the work being cited. If you want to
inconvenience readers by pointing to internal bibliographies rather than online
HTML documents, where available, that’s an editorial choice. But in any event,
for every external reference, give the internal reference in the work being
cited.

Your readers will appreciate it and it could make your work more accurate as
well.

-- 
You are receiving this mail because:
You are the QA Contact for the bug.

Received on Friday, 13 February 2015 21:21:14 UTC