diff --git a/hw/ip/otbn/util/shared/operand.py b/hw/ip/otbn/util/shared/operand.py
index c05fe54..1b0c0be 100644
--- a/hw/ip/otbn/util/shared/operand.py
+++ b/hw/ip/otbn/util/shared/operand.py
@@ -548,9 +548,8 @@
 
     def markdown_doc(self) -> Optional[str]:
         # Override from OperandType base class
-        parts = ['Syntax table:\n\n'
-                 '| Syntax | Value of immediate |\n'
-                 '|--------|--------------------|\n']
+        parts = ['| Assembly Syntax | Value |\n'
+                 '|-----------------|-------|\n']
         for idx, item in enumerate(self.items):
             parts.append('| `{}` | `{}` |\n'
                          .format(item, idx))
diff --git a/hw/ip/otbn/util/yaml_to_doc.py b/hw/ip/otbn/util/yaml_to_doc.py
index 1bd7a05..3dbd2a1 100755
--- a/hw/ip/otbn/util/yaml_to_doc.py
+++ b/hw/ip/otbn/util/yaml_to_doc.py
@@ -13,7 +13,7 @@
 from shared.bool_literal import BoolLiteral
 from shared.encoding import Encoding
 from shared.insn_yaml import Insn, InsnsFile, InsnGroup, load_file
-from shared.operand import Operand
+from shared.operand import EnumOperandType, OptionOperandType, Operand
 
 _O2EDicts = Tuple[Dict[str, List[str]], Dict[int, str]]
 
@@ -301,11 +301,35 @@
     # Show operation pseudo-code if given
     if insn.operation is not None:
         parts.append('{} Operation\n\n'
-                     '```python3\n'
+                     .format('#' * (heading_level + 1)))
+
+        # Add a handy header to remind readers that enum operands and option
+        # operands are referred to by their integer values.
+        not_num_ops = []
+        for operand in insn.operands:
+            if ((isinstance(operand.op_type, EnumOperandType) or
+                 isinstance(operand.op_type, OptionOperandType))):
+                not_num_ops.append(operand.name)
+
+        if not_num_ops:
+            if len(not_num_ops) == 1:
+                op_str = ('operand `{}` is referred to by its'
+                          .format(not_num_ops[0]))
+            else:
+                op_str = ('operands {} and `{}` are referred to by their'
+                          .format(', '.join('`{}`'.format(e)
+                                            for e in not_num_ops[:-1]),
+                                  not_num_ops[-1]))
+
+            parts.append('In the listing below, {} integer value.\n'
+                         'The operand table above shows how this corresponds '
+                         'to assembly syntax.\n\n'
+                         .format(op_str))
+
+        parts.append('```python3\n'
                      '{}\n'
                      '```\n\n'
-                     .format('#' * (heading_level + 1),
-                             insn.operation))
+                     .format(insn.operation))
     return ''.join(parts)