diff --git a/replacements.yaml b/replacements.yaml
index 6114203..f200aa2 100644
--- a/replacements.yaml
+++ b/replacements.yaml
@@ -1,3 +1,7 @@
+# This section contains aliases for use in later sections. This makes it so
+# you don't have to remember and repeat quest IDs, for example, but can refer
+# to them by variable names instead.
+# Note that adding new definition sections requires a plugin update.
 definitions:
   quests:
     # final msq for A Realm Reborn
@@ -5,6 +9,52 @@ definitions:
     # end of Dragonsong War
     - &patch3.3 67783
 
+# This section contains most of what the plugin does. Each list item represents
+# a specific NPC text balloon that should be replaced.
+
+# replacements:
+#   # id (uint) (required)
+#   # This is the ID from the Balloon excel sheet
+#   - id: 123
+#     # text (string) (optional)
+#     # This text will be used instead of the normal text if there either are
+#     # no entries in the "when" section or if none of them match.
+#     text: |-
+#       It's not so bad
+#       being green.
+#     # when (list) (optional)
+#     # This section contains a list of items to check. If any of the conditions
+#     # are met, the text from the item will be used for the balloon.
+#     # Note that the *first* item to match will be used.
+#     when:
+#       # level (list object)
+#       # This when item specifies text that should be displayed depending on
+#       # the player's level.
+#       - level:
+#           comparator (uint) (required)
+#           # Inside the level object you should specify the comparator and the
+#           # text. The comparator can be greaterThan, lessThan, or equalTo.
+#           greaterThan: 49
+#           # text (string) (required)
+#           text: |-
+#             You look like you've
+#             got some experience.
+#       # quest (list object)
+#       # This when item specifies text that should be displayed depending on
+#       # the status of a quest.
+#       - quest:
+#           # id (uint) (required)
+#           # This is the quest ID, visible in the excel sheets or Garland
+#           # Tools.
+#           id: *patch2.0
+#           # text (string) (required)
+#           text: |-
+#             I can't believe you made
+#             it out of Porta Decumana!
+
+# Please also include the original text and location of the NPC as comments
+# above the replacement.
+
 replacements:
   # Original: Just what we need. Another outsider.
   # New Gridania (X: 12.2 Y: 12.0)