Re: [Widgets] - Requirements Working Draft 23 June 2008 Review

Hi Benoit,
Thank you for taking the time to prepare a detailed review. I think I
was able to address all your comments, except for the one about "R27.
Widget State Change Events".  It would be great if you could help
clarify what you want me to do there. Please see below for detailed
description of the changes I made.

Please let me know if you are satisfied with the responses I've have
given below or if you would like any further clarification.

On Wed, Jul 30, 2008 at 8:52 AM, SUZANNE Benoit RD-SIRP-ISS
<benoit.suzanne@orange-ftgroup.com> wrote:
> Marcos,
> Here are my comments on the Requirements (W3C Working Draft 23 June 2008)
>
>
>> 1. Introduction
>> [...] This document does not address the requirements of "web widgets",
>> such as iGoogle Gadgets or Windows Live Gadgets.
> I Think we can add a wording at the end of the sentense to read: "...,
> although this version of the widget specification, the Working group will
> address the web widget in the next iteration of the widgets specifications."

Although I personally agree, I don't think we have reached a
resolution as a working group about what features should be included
in future versions of the Widgets specification. I don't want to
prematurely commit us to feature which we may not end up implementing
in the future. If anything, this should go into a "Widgets 2.0
Requirements" document. It might be good to prepare such a document
once this one reaches CR.

>> 3. Design Goals
>> Longevity: ...
> I think in this chapter we should talk about the versioning of a widget. I'm
> not sure it should be presented as a specific item, or if it can be added
> inside the logevity section in relation to the longevity of the content
> provided and related updates it will need over time.

I see what you are saying, but I think mentioning versioning is better
served in the "Web and offline distribution" section. I've added the
following text:

  "A conforming specification needs to deal with cases where an
end-user acquires a widget resource over HTTP or via some other non
HTTP-based (offline) means, such as a local file system, Bluetooth or
a Multimedia Message Service. In addition, a conforming specification
needs to provide a means by which widgets can be updated when a new or
different version of a widget becomes available. It must be possible
to perform updates from either an online or offline source. "

>> R7. Internationalization Guidelines
>> Rationale: [...] (e.g. 'resources/en/' for all English content,
>> 'resources/en-au/' for further localized Australian-English content, and so
>> on).
> Insert an "and" in between the 2 english example to stress the need to allow
> both

Done.

>>R15 & R16
> Is there a reason why they should not be "must" instead of "should"?

I've changed R15 to a must, as we have already spec'd the <license>
element. We are still undecided about rendering dimensions (R16).

>> R19. Iconic Representations
>> Rationale: [...] For example, an a small graphic of a calendar may
>> represent a calendar widget.
> "an a" should be corrected

Fixed.

> But I propose to add the following after: "And a small graphic of today's
> calendar page may also represent this same calendar widget"

I changed the text to read: "For example, a small graphic of a
calendar showing today's date may represent a calendar widget." This
is to incorporate your suggested text and to imply that the graphic
may change dynamically (in accordance with R34 - Icon API).

>> R27. Widget State Change Events
> This requirement must be available both ways, you should be able to capture
> the change of state when it happens, but you should also be able as an
> author to force the state change as well. I propose the following text:
> "A conforming specification must also allow the author to programmatically
> change the state of the widget to allow a change in the view of the
> instantiated widget."

I'm not sure this is the right place for this. I think this should be
in R24. Instantiated Widget API. However, I'm not sure that the
proposed text covers the actual requirement. I wanted to put something
like you suggested into R24: "The API SHOULD also also allow authors
to programmatically change the visual state of a widget", but I'm not
sure what that means. Can you please provide an example or a use case?

>> R28. Network State Change Events
> In the specific case of a network drop, the author will need to know when
> the network works again, in order to not have to code a checking loop, it is
> important to put together a mechanism whereby it's the widget engine that
> wakes up the widget when the network is back on.
> What do you think?

Agreed. Does the way the requirement has been rewritten in regards to
events address the looping issue?:

"A conforming specification MUST specify a means that allows authors
to check if the widget resource is connected to the network. A
conforming specification MUST define the scope of the term "network"
and MUST specify a means by which connection and disconnection events
can be captured by an author through script. A conforming
specification MUST NOT guarantee event delivery, as there may be cases
where a device is running low on power and can not afford to deliver
them."


>> R29. Modal Priority
>> [...] (or any of its windows) should to categorize itself
> "should to..." should be corrected

Fixed.

>> 4.5 User Agents
>> R39. End-user Declared Proxy
>> A conforming specification should recommend that widget user agents allow
>> end-users to explicitly input a proxy server through which all HTTP-based
>> request are made.
> This requirement should include at the end ", or in case of availability,
> that the system wide proxy is used."
> This requirement should be a "Must"

Using your text as a guide, I reworded the requirement as:

"A conforming specification MUST recommend that widget user agents
allow end-users to explicitly select a proxy server through which all
HTTP-based request are made. In the case where a default proxy has
been defined for the operating system, a conforming specification MUST
recommend that widget user agents find and make use of any default
proxy exposed by the operating system. "

I also renamed R39 to "Proxy Support"

>>R40. Automatic Updates
> This requirement should be a "Must"

fixed.

>>R41. Persistent Storage of Preferences
>>   A conforming specification must recommend that a widget user agent
>> implement a means to persistently store user preferences for each
>> instantiated widget.
> The following should be added after the first sentence: "This Storage
> mechanism must allow to keep the preferences after restart of the widget or
> on the restart of the user agent.

Ok, the requirement now reads:

"A conforming specification MUST recommend that a widget user agent
implement a means to persistently store user preferences for each
instantiated widget. A widget user agent MUST persistently retain a
widget's preference in the case where a widget is re-instantiated or
the widget user agent is restarted."

>> Rationale: To allow widgets to be closed and re-instantiated without the
>> end-user having reset the preferences for an instantiated widget. For
>> example, when using a weather widget, the end-user will want to store the
>> preferred location for weather information, and not be asked to input that
>> information again every time the widget is re-instantiated.
> And again at the end of this sentence: "The same would apply if the user has
> setup 2 instances of the same widget and would like to view 2 different
> cities. After closing the widgets, open 2 instances of this weather widget
> would automatically pick up the 2 pre-set cities.

Ok, included your example by modified the text. Here is the rewrite:

"To allow widgets to be closed and re-instantiated without the
end-user having to reset the preferences for an instantiated widget.
For example, when using a weather widget, the end-user will want to
store the preferred location for weather information, and not be asked
to input that information again every time the widget is
re-instantiated. The same would apply if the user has instantiated two
instances of the same widget and would like to see the weather
forecast for two different cities (e.g., Paris and Sydney). When the
widgets are re-instantiated, the corresponding weather information
would be downloaded to match each widget's city preference."


>> R41 and R42
> I would switch them around so that the notion of the multiple instance can
> be used in the Preference Storage Requirement.

Good point. Fixed.

>> R44. Runtime Security Exceptions
> A conforming specification must specify runtime exceptions for when the API
> attempts to perform an action it it not authorized to perform.
> Correct "it it"

fixed.


-- 
Marcos Caceres
http://datadriven.com.au

Received on Thursday, 31 July 2008 05:01:06 UTC