canmove, Confirmed users
2,675
edits
WebAPI/DesignGuidelines: Difference between revisions
→Preparation: if this is your first, get a co-editor. publicly document, Web Intents as example of scope creep to avoid, keep documenting on an open wiki page
(Clarified html/css/js versions) |
(→Preparation: if this is your first, get a co-editor. publicly document, Web Intents as example of scope creep to avoid, keep documenting on an open wiki page) |
||
| Line 7: | Line 7: | ||
* if this is (one of) your first web APIs, keep your scope narrow. | * if this is (one of) your first web APIs, keep your scope narrow. | ||
** with some experience, you'll see fundamental issues with the web platform for which you can propose fixes! | ** with some experience, you'll see fundamental issues with the web platform for which you can propose fixes! | ||
* discuss | ** if this is your first web API, work with a co-editor that has bandwidth to help you. | ||
* publicly discuss & document use-cases, motivations, and design sketches early, often, and widely (e.g. [[IRC]], applicable W3C/WHATWG lists, [https://lists.mozilla.org/listinfo/dev-webapi dev-webapi], [https://lists.mozilla.org/listinfo/dev-platform dev-platform], [https://lists.mozilla.org/listinfo/dev-gaia dev-gaia], blogs, Twitter, GitHub issues, etc.). | |||
* avoid scope creep by avoiding trying to fix unrelated problems. | * avoid scope creep by avoiding trying to fix unrelated problems. | ||
* iterate and only expand your scope as new features are | ** For an example of what NOT to do, see Google's "Web Intents", which scope creeped to try solve all data-to-code-or-service binding/launching problems. | ||
* iterate and only expand your scope as new features are justified by documented use-cases. | |||
* start with '''use cases and requirements'''. | * start with '''use cases and requirements'''. | ||
* collect currently shipping, available for use '''examples from other platforms''' (ex. Android, iOS). | * collect currently shipping, available for use '''examples from other platforms''' (ex. Android, iOS). | ||
| Line 19: | Line 21: | ||
* show that there is enough consensus making this a good candidate for standardization (the <picture> element did this). | * show that there is enough consensus making this a good candidate for standardization (the <picture> element did this). | ||
** find developers that would make use of this. | ** find developers that would make use of this. | ||
** if you can't find any interested parties then this may not be the right time to standardize your API. | ** if you can't find any interested parties then this may not be the right time to standardize your API, keep developing it on an open wiki page incrementally so that others that may be interested might find it in the future. | ||
* document potential abuse cases and attack vectors. | * document potential abuse cases and attack vectors. | ||
** you don't have to know how to address the concerns, just document them. | ** you don't have to know how to address the concerns, just document them. | ||