What should be in the spec for affordances?

[iherman]

Before starting a discussion on the individual affordances' issues, the WG should have a consensus on what exactly is to be defined for each of those.

[iherman]

Here is a possible first list for each (not necessarily in this order):

1. (Normative) Short description of what the features means. This should be normative, i.e., precise and, as much as possible, exhaustive.
2. (Normative) Note on whether this feature is a MUST, SHOULD, or MAY for a UA in publication mode.
3. (Informative) Reference to the use case(s) in the Use Case document. For “MUST” or “SHOULD” feature there must be such a use case.
4. (Informative) If applicable, the extra OWP features that may have to be added to OWP for a possible (easy?) implementation of that feature. The WG may then have to lobby by the relevant WG-s (HTML, CSS, etc) whether the addition of those extras is feasible.
5. (Informative, and may not be part of the final text) What does it mean to test this feature. Both from the point of view of a general W3C test, as well as for the purpose of an eventual epubcheck-like service.

The open question in my mind whether this WG would have to engage into lower level specifications around item (4) above. (Eg, whether to define some API-s to describe text search over several resources.) My personal opinion is that this should not be done by this WG, but it is worth considering and have a consensus on it.

Anything else?

[rdeltour]

I personally see the affordances as a way to identify the technical gap between what the Web offers today and what’s needed for Web publications, but not necessarily as something that requires being specified as normative statements.

@iherman: you’re suggesting to define affordances as normative (RFC2119) statements; do you mean that these should eventually be made into a rec track deliverable?

If yes, I would be wary of adopting this top-down approach (which –to the extent of my limited knowledge– doesn’t have much precedent in Web standardization). If have a collection of statements along the lines of “A UA MUST do <insert your fave high-level affordance>”, we put the onus on the UA to implement Web pub as an all-or-nothing beast, which isn’t likely to happen with Web browsers.

Also, keep in mind that we’ll have to define an error-handling model: what will happen when a UA doesn’t implement affordance X which is a MUST? Is there any usefulness in declaring a UA “Web publication conformant” (or not)? I think that even if one of the MUSTs is missing, there could still be a variety of things that can be useful for the end user.

In my opinion, the definition of affordances are "just" an intermediary step, after the use cases, and can be loosely described. With a list of affordances on hand, we’ll be able to better identify the technical pieces that are missing in the Web, and how to articulate these with one another, and with the current Web standards. That will hopefully give us a list of technical things to specify, where technical things could be extensions to current specs (app manifest members, CSS feature queries, CSS properties) or new specs altogether (API, declarative data structures).

It is also my expectation (and my hope) that these technical things will be low-level. Some of them will have to be defined by this WG, some of them should better be handled by other WGs (CSS) but pushed and driven by us (by us read @dauwhe 😄). A set of low-level, as-independent-as-possible things is easier to implement, easier to work around individually, and increase the likeliness of adoption and usefulness to the Web.

So, to answer the original question, I think we need to define affordances informatively, but as precisely as possible, and perhaps identify which are critical, and which are nice to have.
The next step is the identification of the possible technical implementation approaches, and whether there’s a gap in the Web. That would be point (3) in your list, but I think it’s really independent from the definition of the affordances themselves. I wouldn’t worry about (4) just yet, as the thing will need to test will be the low-level things we specify to enable the affordances, not the affordances themselves.

[iherman]

@rdeltour I find your arguments compelling, so I am not strongly in favour of the normative/informative notions in the RFC sense. But (as you say) we must try to be as prescriptive as possible every step of the way.

[WSchindler]

Would it not make sense to distinguish between specific metadata (in the manifest or in the primary resources) which are an integral part of the WP and which enable to implement specific affordances. For example on the basis of an exhaustive list of primary resources and a default reading order the notion of "moving forward and backward" is pretty obvious. Should we perhaps have a separate category prerequisites in our template that could describe the data/metadata requirements for a specific affordance? I could imagine that for many affordances the decisive prerequisite would be that the WP can be treated as a logical unit.
To translate an affordance into reality, a UA has to implement a special feature. For obvious reasons, we can't control whether, how and when an affordance will be implemented by browser developers or RS developers. But I think we should describe the expected behaviour of a UA - independent of a specific implementation - to define the UX on an abstract, descriptive level. I personally think we should not be too shy to define our needs (as publishers and users/customers), knowing that in real life not everything will happen as desired.

[ghost]

Yes I agree with "we should describe the expected behaviour of a UA" and metadata should be separate from affordance but some of them do have some relationship or dependency. I think the prerequisities is a good idea to avoid conflict for example some metadata is not a MUST but the affordance which depends on the metadata is a MUST. I also think this could be a step further discussion once we have the template since it sounds more like discussion about which part of affordance is a MUST which is a SHOULD.

In terms of if we need to define if an Affordance X is a MUST, I think we could have part of Affordance X to be a MUST. For example when a UA is switching to publication mode it MUST let user know about it. And provide some way to switch back. On the other hand, pagination will not be a MUST. If UA can not support pagination mode well it can let user scroll. However, I feel we don't need to emphasis normative too much we can put it inside each of feature we defined at here.

Considering above comments, here is my suggestion for template of each feature (base on #143 (comment), basically almost same) for discussion

1. (Normative) Short description of what the features means. This should be normative, i.e., precise and, as much as possible, exhaustive, provide normative information for example "UA must do xxx if support this feature".
2. (Informative) Reference to the use case(s) in the Use Case document.
3. (Informative) Provide example for recommendation of the feature (for example https://www.w3.org/TR/css-regions-1/images/menu-wide.png from css-rigions-1) even though it is not supported yet.
4. (Normative) Dependency. If depends on manifest, infoset or relate to other WG-s output, provide reference..
5. (Informative, and may not be part of the final text) What does it mean to test this feature. Both from the point of view of a general W3C test, as well as for the purpose of an eventual epubcheck-like service. For the affordance item which can be break into low-level spec maybe provide low-level spec test would be useful? How can we say UA can support this feature (to let this spec move forward to CR?)?

[iherman]

@rakutenjeff, my only disagreement with what you propose is the choice of normative vs. informative. We must be very careful about normativeness (see also a previous comment). Describing a feature normatively when the implementation of the feature is not normative sounds counterintuitive to me.

To make my proposal clear(er), I have taken your list and slightly modified it:

1. Short description of what the features means. This should be precise and, as much as possible, exhaustive, provide information for example "UA must do xxx if support this feature".

   If this affordance is a MUST, i.e., we require a conforming user agent to implement it, then this description is normative, otherwise it is informative.

2. Dependency. If the affordance depends on the manifest/infoset then those items should be clearly defined in the manifest/infoset. If there is a dependence on other WG-s output, provide reference.

   If this affordance is a MUST, i.e., we require a conforming user agent to implement it, then these manifest/infoset items are labeled as REQUIRED, otherwise they may be optional.

   If this affordance is a MUST, i.e., we require a conforming user agent to implement it, then the external reference must be normative, otherwise it is informative.

3. Reference to the use case(s) in the Use Case document. (Informative)

4. Provide example for recommendation of the feature (for example https://www.w3.org/TR/css-regions-1/images/menu-wide.png from css-rigions-1) even though it is not supported yet. (Informative)

5. (Informative, and may not be part of the final text) What does it mean to test this feature. Both from the point of view of a general W3C test, as well as for the purpose of an eventual epubcheck-like service. For the affordance item which can be break into low-level spec maybe provide low-level spec test would be useful? How can we say UA can support this feature (to let this spec move forward to CR?)?

I am not sure we will many (if at all?) normatively required affordances. You cite the affordance whereby a User Agent MUST provide information to the User that it operates in publishing mode; this may be one of those indeed. I must admit nothing else comes to my mind.

[ghost]

Thanks @iherman . Yes I was confused between normative and informative sometime :) . I totally agree with the current proposal. I don't have anything more to add but one thing I want to be a bit more clear is it could be some affordance feature itself is not a MUST but if UA is going to support this affordance, some of sub item would become MUST . It could also depend on scope of each affordance item though. That is also the reason I was trying to avoid put normative to a very emphasis position.
What do you think next step for this issue? (I don't have any experience to work on a task yet. I am still slowly learning :) ) Maybe need to ask for TF feedback? Or put on discussion in coming call when get chance?

[iherman]

@rakutenjeff

Can you give an example for:

it could be some affordance feature itself is not a MUST but if UA is going to support this affordance, some of sub item would become MUST.

please?

I think that this more a matter of mutual dependencies of affordances; this should be documented. These do not have an effect on the normativeness of a statement or not, except that if the "larger" affordance is a MUST in the spec, then the dependency should also be a MUST.

It would be good if we had a TF agreement on the proposal, though, so that we can move on to individual affordances.

ping @mteixeira-wwn @jmulliken

[ghost]

@iherman For example here https://github.com/w3c/wpub/blob/master/index.html#L1152 of the individual item Switch to publication mode. It includes MUST , SHOULD and MAY sub items.

[iherman]

@rakutenjeff those texts are all early drafts and must be reviewed also in this respect. The discussion we just had will help straightening those out, hopefully...

[ghost]

Got it. Thanks @iherman

[ghost]

The reason we want to give an example of affordance item in #4 is to give visualized information to reader about what we want to define in this specific affordance item.
It does not need to be already implemented in UA can be just a image or snapshot about what we think it should be or recommend it should be as the example image of css-rigions-1 in the above comment.

[wareid]

Affordances addressed in the UCR document, as mentioned in the meeting on Feb 4 2019, I am closing this issue.