1 files changed, 69 insertions, 0 deletions
diff --git a/GLOSSARY.md b/GLOSSARY.md
new file mode 100644
index 0000000..664edd9
--- /dev/null
+++ b/GLOSSARY.md
@@ -0,0 +1,69 @@
+# Glossary
+
+This is meant to give a rough overview of (train-related) terms used in
+this code; both for others as a reference and for me so I can remember
+to use them in a (somewhat) consistent way, since they are somewhat
+arbitrary. I've tried to remain at least broadly close to the
+terminology used by GTFS.
+
+## Terms
+
+(Calendar-)Date / Day
+:   A single, unique day (e.g. 1970-01-01). Usually used to indicate if a
+    *trip* is running on that day or not.
+
+Time (of Day)
+:   Time on a given day, given in seconds (though often displayed as
+    minutes) since midnight. If a trip crosses midnight it is treated as if
+    it took place entirely on the previous day, and times simply count up
+    beyond the total number of seconds in a day (note that that's a
+    timezone-series dependent number).
+
+Trip (don't confuse with Train)
+:   Used as in GTFS: a trip is a defined sequence of *stops*, referred to by
+    a number (called its trip ID, e.g. IC 94). Usually runs on multiple
+    days. Always has an associated *shape*.
+
+    (might match your intuition for "train line")
+
+Stop
+:   A *station* with associated arrival/departure *time*.
+
+Station
+:   A train station. Tracktrain refers to each by an ID, and hopefully knows
+    its geolocation.
+
+Shape
+:   A sequence of geolocations describing a line between stations,
+    describing the physical railway along which trains travel.
+
+Train (don't confuse with Trip)
+:   A single instance of a *trip* on a concrete *date*. Tracktrain mostly
+    concerns itself with keeping track of those; the rest is just additional
+    stuff.
+
+Vehicle
+:   An actual, physical vehicle, which might act as the *train* going along
+    a *trip* on a certain *date*.
+
+    For now tracktrain doesn't really care about them (but if it's curious
+    it might yet learn about them!)
+
+Announcement
+:   The thing that GTFS calls "Service Alert" --- a text message giving
+    human-readable information about some *train*.
+
+(Train-)Ping
+:   A single packet of data sent from a train's *OBU*. Might arrive in some
+    arbitrary order.
+
+Control Room
+:   The "admin interface" of tracktrain, which is not meant to be used by
+    on-board staff.
+
+On-Board Unit (OBU)
+:   A thing on a vehicle which does geolocation tracking and yells at
+    tracktrain about it.
+
+    If we ever run into potential confusion regarding this term we're
+    probably way too professional to actually use tracktrain for anything.