:memo: Update examples docs.

2 files changed, 27 insertions, 9 deletions

diff --git a/examples/03-controlled-inputs/README.md b/examples/03-controlled-inputs/README.md
index 30fda75..95ca620 100644
--- a/examples/03-controlled-inputs/README.md
+++ b/examples/03-controlled-inputs/README.md
@@ -18,8 +18,9 @@ two things:
 ui.input([
   // Input's value is fixed to the model's `value` field
   attribute.value(model.value),
-  // Whenever the input changes, we send a `GotInput` message with the new value
-  event.on_input(GotInput)
+  // Whenever the input changes, we send a `UserUpdatedMessage` message with the
+  // new value
+  event.on_input(UserUpdatedMessage)
 ])
 ```
 
@@ -36,7 +37,7 @@ value is less than 10 characters long.
 
 ```gleam
 case msg {
-  GotInput(value) -> {
+  UserUpdatedMessage(value) -> {
     let length = string.length(value)
 
     case length <= model.max {
@@ -48,6 +49,20 @@ case msg {
   ...
 ```
 
+## A note on message naming
+
+In our [state management guide](https://hexdocs.pm/lustre/guide/02-state-management.html)
+we touch on the idea of "messages not actions." We think the best way to name your
+messages is following a "Subject Verb Object" pattern: `UserUpdatedMessage` not
+`SetMessage` and so on.
+
+This approach to message naming can feel a cumbersome at first, especially for
+small examples like this. One of Lustre's super powers is that as your app grows
+in size, your `Msg` type becomes a very helpful overview of all the different
+events your app can handle. When they take the form of `Subject Verb Object` it
+gives you an immediate sense of the different things that speak to your app: how
+much is coming from your backend, how much is user input, and so on.
+
 ## Getting help
 
 If you're having trouble with Lustre or not sure what the right way to do
diff --git a/examples/03-controlled-inputs/src/app.gleam b/examples/03-controlled-inputs/src/app.gleam
index d3c764e..f620e6a 100644
--- a/examples/03-controlled-inputs/src/app.gleam
+++ b/examples/03-controlled-inputs/src/app.gleam
@@ -35,13 +35,13 @@ fn init(_) -> Model {
 // UPDATE ----------------------------------------------------------------------
 
 pub opaque type Msg {
-  GotInput(value: String)
-  Reset
+  UserUpdatedMessage(value: String)
+  UserResetMessage
 }
 
 fn update(model: Model, msg: Msg) -> Model {
   case msg {
-    GotInput(value) -> {
+    UserUpdatedMessage(value) -> {
       let length = string.length(value)
 
       case length <= model.max {
@@ -49,7 +49,7 @@ fn update(model: Model, msg: Msg) -> Model {
         False -> model
       }
     }
-    Reset -> Model(..model, value: "", length: 0)
+    UserResetMessage -> Model(..model, value: "", length: 0)
   }
 }
 
@@ -67,10 +67,13 @@ fn view(model: Model) -> Element(Msg) {
       ui.field(
         [],
         [element.text("Write a message:")],
-        ui.input([attribute.value(model.value), event.on_input(GotInput)]),
+        ui.input([
+          attribute.value(model.value),
+          event.on_input(UserUpdatedMessage),
+        ]),
         [element.text(length <> "/" <> max)],
       ),
-      ui.button([event.on_click(Reset)], [element.text("Reset")]),
+      ui.button([event.on_click(UserResetMessage)], [element.text("Reset")]),
     ),
   )
 }