diff --git a/index.bs b/index.bs
index df46ab80..621b37cb 100644
--- a/index.bs
+++ b/index.bs
@@ -8,6 +8,7 @@ Editor: Domenic Denicola, Google https://www.google.com/, https://domenic.me/, d
ED: https://w3ctag.github.io/design-principles
Abstract: This document contains a small-but-growing set of design principles collected by the W3C TAG while reviewing specifications.
Default Biblio Status: current
+Markup Shorthands: markdown on
!Participate: GitHub w3ctag/design-principles (file an issue; open issues)
Link Defaults: html (dfn) queue a task/in parallel/reflect
@@ -99,7 +100,7 @@ Names take meaning from:
* use (how people come to understand the name over time)
* context (the object on the left-hand side, for example)
-Consistency is a good principle that helps to create a platform that users can navigate intuitively
+Consistency is a good principle that helps to create a platform that users can navigate intuitively
and by name association.
Please consult widely on names in your APIs.
@@ -212,6 +213,30 @@ examples that violate the above rules are XMLHttpRequest
and
initialisms, even if they are repeated.
+
Always add event handler attributes
+
+For an object that inherits from `EventTarget`, there are two techniques available for registering
+an event handler (e.g., an event named "somethingchanged"):
+
+1. `addEventListener` which allows authors to register for the event using the event's name
+ (i.e., `someobject.addEventListener("somethingchanged", myhandler)`) and
+2. `onsomethingchanged` IDL attributes which allow one event handler to be directly assigned to the
+ object (i.e., `someobject.onsomethingchanged`).
+
+Because there are two techniques for registering events on objects inheriting from `EventTarget`,
+authors may be tempted to omit the corresponding event handler IDL attributes. They may assume that
+event handler IDL attributes are a legacy registration technique or are simply not needed given that
+`addEventListener` is available as an alternative. However, it is important to continue to define
+event handler IDL attributes because:
+
+* they preserve consistency in the platform (e.g., several media-related event handler IDL
+ attributes are defined on the `Window` and `Document` interfaces despite the fact that
+ implementations will never dispatch those events to those objects)
+* they enable feature-detection for the supported events
+
+So, if the object inherits from `EventTarget`, add corresponding `on...` event handler attributes to
+the interface.
+
Types and Units
Use numeric types appropriately
@@ -351,10 +376,10 @@ is done in a consistent and privacy-friendly way:
stable id during the session for the given origin, but also be able to deterministicly produce
the same id in subsequent sessions.
-
+
Other API Design Considerations
-It is important not to neglect other aspects of API design such as privacy and security. Please
+It is important not to neglect other aspects of API design such as privacy and security. Please
take advantage of these other excellent resources in your design process:
* Privacy Considerations for Web Protocols