diff --git a/tools/map/clusters.map b/tools/map/clusters.map
index 8c4ff5636..f69cf2747 100755
--- a/tools/map/clusters.map
+++ b/tools/map/clusters.map
@@ -1,3 +1,12 @@
+#####################################################################
+# The Ur-Quan Masters official cluster definitions
+# (used by starmap image generation scripts)
+#
+# Fields are:
+#   Cluster name,
+#   Name positioning hint (navigational abbr; not currently used),
+#   Connecting line pairs (comma separated; latin: A=1, B=2, etc)
+#####################################################################
 Andromedae,s,AB
 Antliae,ne,AB,BC,BE,CD,EF,FA
 Apodis,w,AB,BC,CD,DA
diff --git a/tools/map/stars.map b/tools/map/stars.map
index 3f34d4101..2c0594e08 100755
--- a/tools/map/stars.map
+++ b/tools/map/stars.map
@@ -1,3 +1,15 @@
+#####################################################################
+# The Ur-Quan Masters official star definitions
+# (used by starmap image generation scripts)
+#
+# Fields are:
+#   Star/cluster name,
+#   Star designation in a cluster (or * for singular),
+#   X coordinate (in grid coords),
+#   Y coordinate (in grid coords),
+#   Color (must match whatever the parent script has),
+#   Size (usually 1-3)
+#####################################################################
 Achernar,*,537.5,272.9,B,1
 Alcor,*,970.8,025.0,B,1
 Aldebaran,*,737.5,356.2,B,1