Eyes Above The Waves

On Monday I gave a talk at the Victora University computer science department which I called "API Design For The Masses". I've put the slides online. The premise is that designing specifications for the Web requires you to make different decisions than in the "good old days" when a relatively small number of professionals were writing specifications and implementing both sides of those specifications. I give eight design principles for Web-scale specs, mostly based on examples.

The contents should not be surprising to anyone involved with the WHATWG. I didn't invent these principles, I just wanted to summarize my version of some of what the community already knows.

These are my principles:

1. Try to define behaviour for all inputs. Avoid "undefined" behaviours. Simplify or eliminate "fatal" behaviours.
   
2. Specs that contradict entrenched practice must be changed to match it. If following the spec harms users, that part of the spec is worthless.
   
3. Standardization and implementation must happen concurrently. You need a fast feedback loop, which means you need to be able to update the spec frequently and with low latency.
   
4. Provide non-standard/pre-standard extensions, but use syntax to ensure authors know they're non-standard.
   
5. Favour evolution over revolution if possible.
   
6. Aim for forward and backward compatibility (with graceful degradation). Avoid versioning.
   
7. Encourage conditional content to use detection of features, not detection of implementations. Provide mechanisms for such conditionals.
   
8. Only add features where authors can see and correct their mistakes. Invisible metadata doesn't work.