RE: CfC: publish FPWD of Fullscreen spec; deadline May 24


[Anne van Kesteren:]

> 
> I don't really see how this is a helpful contribution. I fully realize
> everything is not as good as it can be (and you know I do), but we have
> limited resources and many problems worth solving. If you know someone
> that can do a better job on CORS or Fullscreen please by all means have
> them do it.

If you saw how it were helpful there would be no need to bring it up, would
there? Use-cases are actually discussed at length on mailing lists; in some 
cases they are even documented on a wiki page. But all this material is often
way too hard to find or gather for folks who aren't regular insiders. So what 
*I* don't see as helpful is the expectation that readers ought to go spelunking 
through months of mailing lists to figure out what a spec is/is not trying 
to solve. 

I'm not suggesting such content should be exhaustive, formal or even normative but 
there is a huge difference between "some of the primary use-cases this spec aims 
to solve are documented in Appendix X" and "nothing else to see here, this is for 
implementation only; if you want to know what this was meant to solve why don't you 
go search the last n years of archives because, well, we have more important problems 
to solve than making sure you really get what this is for". 

From your end I understand how this may sound like overhead since you live in these
mailing lists, write specs for a living and primarily care about the small number
of implementors whose job also includes following these daily conversations.
The result, however, is documents that can be far less useful for everyone else. And,
since even implementors can't follow everything, we also make it more likely some could 
end up using the wrong tool to solve a problem. So that, for instance, you could find 
yourself spending way more time arguing with the Fonts WG about why they shouldn't use 
CORS as a same-origin solution than you would have spent clearly documenting the 
scenarios the spec aims to solve vs. what it's not meant to solve.

Mind you, it's not something I would mandate. But I suggest it would be good 
practice to try this; and that the cost/reward may be positive. 

> I put my time into documenting the platform in a detail I hope is
> sufficient for implementors to reach interoperable implementations which
> helps reducing site compatibility issues and developer frustration. I
> certainly compromise on non-normative material, because there are so many
> parts not documented well.
> 
I'm not suggesting you're the only person who does this or even the worst 
offender. Most specs these days have this limitation (a few do a decent job using
use-cases as examples). Given the growing number of documents and the reach of 
the platform I think this is something we all need to work on in the future.

Received on Thursday, 21 June 2012 19:29:57 UTC