Lea Verou writes about the design of HTML APIs and how we might write better documentation for web designers. An HTML API is term for a JavaScript library that is configured and controlled through HTML rather than through JavaScript. For example <div data-open-modal="#modal"></div> might tell a library that this element is in charge of opening a modal. There is no configuration or initting other than loading the library itself.
My favorite part of this piece is where Lea confronts what might generally be seen as a simple plug-n-play JavaScript library:
Even this tiny snippet of code requires people to understand object literals, arrays, variables, strings, how to get a reference to a DOM element, events, when the DOM is ready and much more. Things that seem trivial to programmers can be an uphill battle to HTML authors with no JavaScript knowledge
By giving folks an HTML API we can avoid potential headache.
…remember that many of these people do not speak any programming language, not just JavaScript. Do not talk about models, views, controllers or other software engineering concepts in text that you expect them to read and understand. All you will achieve is confusing them and turning them away.
Lea’s made a collection of libraries that have HTML APIs.
