Re: referencing W3C recs in the Techniques document

At 10:37 PM 11/23/99 -0500, Ian Jacobs wrote:
>"Gregory J. Rosmaita" wrote:
>> 
>> aloha, ian!
>> 
>> second, i'd like to re-raise an issue that would make the techniques
documents
>> a hell of a lot more usable...  why do all of the links that refer to
specific
>> attributes and elements defined in W3C recommendations lead only to a
top-level
>> link, located in the References section of the document, for the relevant
>> recommendation?
>> 
>> case in point -- under the Accessibility Topic "Link Techniques",
located at
>> (long URI warning)
>> http://www.w3.org/wai/ua/wai-useragent-techs-19991121#link-techniques
>> appears the following technique:
>> 
>> quote
>> Use :before from [CSS2] to clearly indicate that something is a link (e.g.,
>> 'A:before { content : "LINK:" }')
>> unquote
>> 
>> the bracketed term quote CSS2 unquote is a hyperlink that leads not to
the CSS2
>> description of the :before and :after pseudo-elements, as anyone reading
the
>> document for the first time might reasonably expect, but, leads instead
to a
>> link in the References section of the Techniques document, which points
to the
>> top-level URI for the CSS2 recommendation...  would it not be more
logical and
>> informative (not to mention more user-friendly) if the hyperlink pointed
users
>> to the pertinent portion of the CSS2 rec, which in this case would be:
>> http://www.w3.org/TR/1998/REC-CSS2-19980512/generate.html#x2
>> rather than leave the reader to fend for his or her self once he or she is
>> dumped unceremoniously at the top level URI for the relevant rec?
>> 
>> i know that this would entail a considerable effort, and so i volunteer my
>> services to assist in any such transformation,
>
>I'll have to think about this one. I'm torn. For resources that
>are stable (e.g., dated W3C Recommendations) it may not hurt. For
>unstable resources, there is significant risk of links being
>broken and we can't fix them once the document is published. 
>
>I'll take an action item to talk this over in the Team. Also,
>what do others in the WG think?
>

I think Gregory hit the nail on the head with this one.  

Sometimes one wants to target the link up one level of the document tree in
the referenced document from the most local possible reference.  That would
result in a link to
<http://www.w3.org/TR/1998/REC-CSS2-19980512/generate.html> in this case.
However, in this particular case the before: and after: attributes are well
explained in their own section and starting one level up does not add
significantly to the context required for understanding.  So: yes, make the
hyper-references to feature definitions from the techniques document
precise; and yes, this is a good example of the appropriate level of
precision in such references.

If we only reference the top of the specification, a significant fraction
of readers following the link from the techniques document may turn away
from the chase before finding the relevant definition and conclude "It's
all too complicated and hard."

Al

> _ Ian
>
>-- 
>Ian Jacobs (jacobs@w3.org)   http://www.w3.org/People/Jacobs
>Tel/Fax:                     +1 212 684-1814
>Cell:                        +1 917 450-8783
>

Received on Wednesday, 24 November 1999 08:19:29 UTC