diff --git a/warehouse/static/sass/blocks/_notification-bar.scss b/warehouse/static/sass/blocks/_notification-bar.scss
index ee4294efdad0..eb752bb35b72 100644
--- a/warehouse/static/sass/blocks/_notification-bar.scss
+++ b/warehouse/static/sass/blocks/_notification-bar.scss
@@ -30,8 +30,31 @@
   Modifiers:
     - danger: Applies a red background
     - success: Applies a green background
-    - dismissable: Indicates notification be be dismissed. Defaults to hidden.
+    - dismissable: Indicates notification can be dismissed. Defaults to hidden.
     - visible: Indicates a visible, non-dismissed notification
+
+  A notification bar can be made dismissable by adding the following to the main
+  notification-bar div:
+    - .notification-bar--dismissable to its classes
+    - data-controller="notification" as an attribute
+    - data-target="notification.notification" as an attribute
+
+  The data-controller and data-target are used for handling visibility,
+  including adding .notification-bar--visible to notification-bar div if it has
+  not been dismissed (and persisted) yet.
+
+  <div class="notification-bar notification-bar--dismissable"
+    data-controller="notification" data-target="notification.notification">
+      <span class="notification-bar__icon">
+        // icon here
+      </span>
+      <span class="notification-bar__message">
+        // A one line notification goes here.
+      </span>
+  </div>
+
+  Note that if JavaScript is disabled, the notification bar always defaults to
+  be visible.
 */
 
 .notification-bar {