search

w3c / controller-document

Controller Documents
https://w3c.github.io/controller-document/
Other
5 stars 7 forks source link

Syntactically invalid examples push learning curve higher than necessary #118

Open filip26 opened 1 week ago

filip26 commented 1 week ago

Examples should be treated in a better way, many of them are syntactically malformed, many of the others have wrong contexts or different, usually minor like comments, issues preventing from just grabbing an example as is and playing. 

I understand that to some examples are just illustrative, unimportant stuff. To adopters, having examples in a form that is useful is invaluable and might dramatically boost progress with adopting a spec. 

Don't we have test vectors? Yes, but it's a different case, different phase of adoption - need for a compact test case, which is in contrast to examples, to grab and play. 

I'm happy to contribute to that.

(I know, unfortunately this is not the only W3C spec suffering it)

msporny commented 1 week ago

There are a few things we can do in this spec that we've done in others:

  1. We mark comments and ... annotations as "ignore on copy" using some CSS tricks.
  2. We try to make the first few examples syntactically valid.

We just need to do a full pass on the document and try to get it into proper shape, we haven't done that pass yet, but we should.

I'm waiting on PR #116 to land before doing a full pass.