search

therealglazou / webbook

WebBook specification
24 stars 3 forks source link

Rephrase in terms of UA and author (or authoring tool) requirements #6

Open frivoal opened 6 years ago

frivoal commented 6 years ago

A number of requirements in the spec are expressed in the form of "WebBooks must be XYZ", or "WebBooks should have XYZ". These should all be rephrased in terms of requirements on User Agents, authors, authoring tools, validators etc.

This style of spec writing makes it much clearer what to do in error cases. The most important requirements are those on the User Agent, because that forms the basis of interoperability.

Requirements on authors and authoring tools can also be useful, but given that User Agents need to have normatively defined behavior to handle correct AND incorrect content, expectations on content producers can generally be inferred from the requirements on the User Agent.

Finally, we may care about being able to declare a document as conforming or not to the specification. This too is secondary to defining the behavior of User Agents in terms of interoperability and usability, but it may be helpful in terms of branding and growing the ecosystem. That sort of requirements is better described as "Validators MUST ..." than as "Documents MUST ..."

therealglazou commented 6 years ago

Agreed. Not a minor task, though. Not sure this is for the first public release.

frivoal commented 6 years ago

Not sure this is for the first public release.

No, just logging this here to express the intent. I suggest all any addition from now on should be careful to use this approach, and slowly, we should refactor the existing part to match this. Doing this perfectly is a fair bit of work, but as long as we agree that's the end goal, we can gradually approach it.