Users & Requirements for Intro Docs? - Re: Feedback on "Offline Web Applications"

Hey guys,

I really dig these intro docs.  I think they'll go a long way towards helping people understand what we're working on.

I'm new to the group, so I apologize if this has already been asked or covered.   

Do we have any requirements for what and to whom we're trying to communicate to with these intro documents?  Are they for browser makers? Are they for the web app developers?  Are they for everyone?  The requirements, goals, and audience of the doc would color my comments.

Also... is the intention to publish it as a WG note?  What about doing it as a stand-alone article on the HTML WG web site?  Or just w3.org/html ?

I worked a bit on the WAI web site redesign (http://w3.org/WAI).  We did some usability testing and all our users had a significant problem dealing with the way that TR-styled documents are setup.  Multiple identified them as "daunting."

Both WAI and the Internationalization activities to my understanding have found great success publishing supplementary material outside of the TR format.

Examples
* http://www.w3.org/International/getting-started/language 
* http://www.w3.org/WAI/bcase/Overview 

my 2 cents,
- justin


******************
Justin Thorp
US Library of Congress
Web Services - Office of Strategic Initiatives
e - juth@loc.gov
p - 202/707-9541

>>> Julian Reschke <julian.reschke@gmx.de> 11/18/2007 1:54:35 PM >>>

Hi,

below is some feedback on "Offline Web Applications" (Editor's Draft 17 
November 2007) (<http://dev.w3.org/html5/offline-webapps/>).

Summary: if the intent of this is to make people aware of the presence 
of these new things in HTML5, it's working. However, in it's current 
state it really requires the reader to go to the real spec to understand 
what's going on -- that may be ok, but in this case it would be helpful 
if it could point directly to the section of HTML5 containing the full 
details.

Content:

2. SQL -- Not being familiar with what is being defined, I found the 
example a bit confusing. If this is meant to be an introduction, I think 
it would make sense to (1) show the DB creation first and (2) add a few 
sentences about how the API exactly looks like. So what elements does 
openDatabase() take(), why does db.transaction take a function argument, 
what exactly does the executeSQL function expect parameter-wise?

3. Offline Application Caching APIs -- seems the spec defines a new text 
format for defining the application caching. Is there a MIME type being 
defined? Any grammar for the format? Turns out this is defined in 
<http://www.w3.org/html/wg/html5/#manifests>, so it's probably fine to 
leave it out here. However, *what* is defined over there ("Note: This is 
a willful double violation of RFC2046.") makes me nervous. Not sure why 
this isn't simply an XML format; instead of defining yet another special 
text format with (IMHO) quite obscure parsing rules (CR only as line 
delimiter???)

3. Offline Application Caching APIs -- not sure that using "server.cgi" 
as a name is a good idea over here; my understanding was that Cool URIs 
Do Not Change, thus encoding some technology-specific extension into an 
URI generally is not a good idea. Suggest to simply use something like 
"events".

Editorial:

- The Javascript examples do not terminate statements with a semicolon. 
My understanding is that although it's legal, it's discouraged (see 
<http://www.jslint.com/lint.html>). Minimally, it's confusing to read 
for people who have grown up with C and Java.

- "...that takes up one mebibyte of storage." -- Typo?



Best regards, Julian

Received on Monday, 19 November 2007 19:53:47 UTC