Re: References and Modularity

Hi Larry,  


On Friday, June 7, 2013 at 5:28 PM, Larry Masinter wrote:

> Re HTML5 references http://www.w3.org/TR/html5/references.html#references
> and "metadata of references constantly fall out of date":
>  
>  
> Two things: "greatest good for greatest number". It looks like you are trying to optimize
> the work for the editor(s) of specifications.  

Yes, naturally I like to make Editor's lives easier - because I work as one… but...   
> But specifications only have one or a few
> editors, while they have many reviewers. Specifications that are intended to be
> standards should be optimized to for the purposes of standards, and in particular
> the needs of reviewers and users should take higher priority than the amount of
> time an editor spends.

I agree - editors are actually last in my chain of cares. My interest is that implementers, reviewers, and users are always looking at the most stable/up-to-date references.  

To this point, it's why I've been nagging the W3C to make the /TR/ information available in JSON and why I pushed for all specifications to be CORS enabled (they now are!) - so we can dynamically scrape the metadata of specifications to build up references. I also nagged the IETF about CORS-enabling their specs list (they have a big XML file or something), but I never heard back from them.  

So: what I am trying to do at the moment is remove human error from references - humans do a bad job at keeping information up to date, and this punishes reviewers and users. So the best way to deal with the human problems is to limit the amount of things the humans (including me) can get wrong.  
>  
> Secondly you are doing this optimization for the editor at the expense of losing
> cruicial information for the review process, and one of the essential tasks for which
> standards groups have editors: to insure the integrity of the references.

In my model, the review process is continuous and forever ongoing - hence the references have to be tied to the latest and greatest (and the Editor/WG deeply invested in monitoring changes to all specs they reference). Anything else is demonstratively fundamentally flawed: If once cites a WD version, and that WD version gets updated the date after the spec is published, the reference is useless. A reviewer/user can go and look at the now out of date version, and conclude it makes sense, but in reality the cited WD has changed and now the published spec would be wrong.    
> You gave as an example:
>  
> > [ABNF]
> > Augmented BNF for Syntax Specifications: ABNF, D. Crocker, P. Overell. IETF.
> >  
> > Would be just:
> >  
> > [ABNF]
> > Augmented BNF for Syntax Specifications: ABNF. IETF.
>  
>  
>  
>  
> However, the reality is that [ABNF] could have actually changed in ways that
> don't match.

Right, in a living standard model, you just fix the spec that is in error.   
>  
>  
> Look, for example, at the
> discussion in the IETF JSON working group over updated references to [ABNF]
>  
> thread "Update reference for ABNF"
> http://www.ietf.org/mail-archive/web/json/current/msg00405.html  
> thread "Proposed change: update the Unicode version"


That thread concludes with:  
"(Updating is good spec hygiene, and the RFC editor will make you update it anyway. Or the IESG before it.)"

Which underscores my point, no?  
  
> http://www.ietf.org/mail-archive/web/json/current/msg00301.html

And this one:  
"There are other i18n issues that we might want to clarify, but updating the Unicode reference seems uncontroversial."
  
And even better followup from Tim Bray:
"So how about `string is a sequence of zero or more Unicode characters defined in version 6.2 (or any subsequent version) of [UNICODE]`"

Yes, sir… "or any subsequent version" … i.e., the latest and greatest :)  

Note also the clever discarding of section numbers by Tim. Most impressive.  
> you may think these conversations are unnecessary, extra work and burden,
> but they're part of creating one of the things expected of a "standard" --

I think they are great, because they seem to completely validate what I am saying.  
> namely that it has been widely reviewed for consistency. And you can
> only insure wide review for consistency if there are no unreviewed
> changes during a 'last call' period.

You can review for consistency anytime/anywhere. Specs change specially _after_ Last Call. CR is when specs are at their most volatile.    
>  
> Whenever A --normative reference -> B and B updates from B1 to B2,
> that you actually need to REVIEW whether the changes from B1 to B2
> require changes to the language in A.

This is true. In my model, I assume the Editor will continue to track all specs he or she references. This is a fundamental part of maintaining a Living Standard.   
>  
> Your proposal to remove explicit dates and point to the 'latest version'  
> not only removes the opportunity to do this review, it eliminates the
> important information of whether the updated reference has
> been checked for consistency with your use of the previous referenced
> spec.

Kinda, but it's assumed to be part of the Living Document process - and if found to be an issue, one fixes either spec to resolve the issues.   
> The other metadata (title, author/editors, organization publishing) are,
> in addition to the date, important clues -- when you chase a
> URL in A and get 404 Not Found -- as to how you might search for
> the intended specification anywhere, e.g., if it moved.

I bet you can find it without those bits (i.e., only with title and URL). I would like to see at least one example of where a reference in a W3C spec has gone 404 and you can't find it again with the title and the URL through Google or the web archive. It seems like cargo cult behavior (copying from the dead tree academic journal model) for no demonstrable reason. I'm open to being proved wrong on this one.    
> Finally (as a minor point): specifications that don't change substantially
> sometimes get reorganized for clarity, but the reorganization plays
> havoc with references from other specs into the interior. So if you
> say "Section 7.2 of [UNICODE]" but Unicode gets reorganized,
> the new section might have a different section number.

Totally, that's another rule of mine: never ever cite section numbers - only concepts or complete specifications (or tell the editor of the other spec to add suitable id's to their document so you can hyperlink to them).   

Kind regards,
Marcos

Received on Friday, 7 June 2013 17:34:27 UTC