W3C home > Mailing lists > Public > spec-prod@w3.org > October to December 2011

Re: What are the requirements/problems? Re: Working on New Styles for W3C Specifications

From: Noah Mendelsohn <nrm@arcanedomain.com>
Date: Sat, 03 Dec 2011 13:15:14 -0500
Message-ID: <4EDA6732.9090501@arcanedomain.com>
To: Eric Johnson <eric@tibco.com>
CC: Marcos Caceres <w3c@marcosc.com>, "chairs@w3.org" <chairs@w3.org>, "spec-prod@w3.org" <spec-prod@w3.org>

On 12/1/2011 4:20 PM, Eric Johnson wrote:
> The ideal in usability would be to let people annotate the specification,
> and then choose who they wish to share those annotations with (authors,
> public, only themselves). For W3C sanity, the annotated version wouldn't be
> at the official URL....

Let me be a bit of a curmudgeon about this.

I see here an implicit high priority requirement that the core document for 
a specification be enabled for live, collaborative annotation. I think it 
is desirable to have >a version< of a specification that admits such 
collaborative discussion, but for me that's much lower priority than 
ensuring that the primary version is convenient and effective for it's main 
goal, which is to be used as a specification.

Among the things that are high priority for me regarding specifications 

* They should be convenient to read in a wide variety of environments. So, 
anything that slows download or rendering, or makes unnecessarily makes a 
specification too heavyweight to read in, say, a mobile environment, is a 
negative. I can read most any RFC on my smartphone, and most RFCs and W3C 
Recommendations download very quickly to my desktop too. I can't say the 
same of some of the Javascript-enhanced specifications that we are starting 
to see. Even on desktops, I want scrolling and search to be fast and 
without display glitches (some of the annotation frameworks seem to keep 
popping up annotation UI as you scroll or mouse over).

* They should be easy for search engines to index and retrieve. Depending 
on how the framework for enabling annotations is implemented, search 
engines might either have trouble finding the main content of a spec (e.g. 
because it's hidden behind too much Javascript), or might hit on the 
annotations as well as the core text. Sometimes you want to search 
annotations too, but not typically.

* I want copy/paste to work well, so I can select small or large sections 
of a specification and paste them, e.g., into an email. The current W3C 
spec formats, and even the ASCII-only RFC formats do this very well. When 
the screen rendering is full of pop-ups and annotation boxes, copy/paste 
can easily wind up mixing such annotation text with that of the core spec.

* It's desirable if the packaging of spec documents is simple, ideally in a 
single file with a widely deployed MIME type (or, as a compromise, a zip 
with some images). I can send you the file for RFC 2616 as an email 
attachment and not have to send you a zip file full of enabling JavaScript 
libraries. I think it's OK if a bit of formatting depends on an external 
stylesheet, or if JavaScript is used e.g. to highlight links on hover, but 
it's really good if the specification itself stands on its own.  Yes, 
transcluded <img> references are already a compromise in this respect; some 
specifications really need them and some can be read quite effectively 
without them.

For me, enabling live annotations is nice to have, but is somewhat below 
the above in priority order. In any case, I think we should have a good 
debate about requirements and use cases for any new format before we just 
assume that one desiderata or another is an absolute requirement.

Also: as we consider increased use of JavaScript, I'd suggest giving some 
thought to the Rule of Least Power [1], which traces to Tim's early 
writings on Web architecture [2]. It's a really good thing if the documents 
embodying W3C specifications are set out in declarative formats like HTML 
or text/plain, using JavaScript only where really necessary.

FWIW: my >guess< is that I'd be happiest if the specs themselves were not 
mini discussion/annotation wikis. It's fine if there is a second copy of 
each spec that >is< enabled for such live update and annotation, with the 
core versions remaining static and relatively Javascript-free.


[1] http://www.w3.org/2001/tag/doc/leastPower.html
[2] http://www.w3.org/DesignIssues/Principles.html#PLP
Received on Saturday, 3 December 2011 18:15:40 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:16 UTC