docs: [FC-0074] add glossary for openedx-events ecosystem (#407)

docs/how-tos/creating-new-events.rst

@@ -19,7 +19,7 @@ if you have time, you could accompany your proposal with the implementation of t
 2. Place your event in an architecture subdomain
 -------------------------------------------------
 
-As specified in the Architectural Decisions Record (ADR) events naming and versioning, the event definition needs an Open edX Architecture
+As specified in the Architectural Decisions Record (ADR) events naming and versioning, the :term:`event definition <Event Definition>` needs an Open edX Architecture
 Subdomain for:
 
 - The name of the event: ``{Reverse DNS}.{Architecture Subdomain}.{Subject}.{Action}.{Major Version}``
@@ -43,7 +43,7 @@ Refer to `edX DDD Bounded Contexts <https://openedx.atlassian.net/l/cp/vf8XjRiX>
 3. Create the data attributes for the event (OEP-49)
 ----------------------------------------------------
 
-Events send `data attributes <https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0049-django-app-patterns.html#data-py>`_ when triggered. Therefore, when designing your new event definition you must
+Events send `data attributes <https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0049-django-app-patterns.html#data-py>`_ when triggered. Therefore, when designing your new :term:`event definition <Event Definition>` you must
 decide if an existent data class works for your use case or you must create a new one. If the answer is the latter, then try to answer:
 
 - Which attributes of the object are the most relevant?
@@ -103,10 +103,10 @@ Consider the user data representation as an example:
 4. Create the event definition
 ------------------------------
 
-Open edX Events are instances of the class OpenEdxPublicSignal, this instance represents the event definition that
+Open edX Events are instances of the class OpenEdxPublicSignal, this instance represents the :term:`event definition <Event Definition>` that
 specifies:
 
-- The event type which should follow the conventions in the Naming Conventions ADR.
+- The :term:`event type <Event Type>` which should follow the conventions in the Naming Conventions ADR.
 - The events' payload, here you must use the class you decided on before.
 
 The definition created in this step must comply with:

docs/how-tos/using-events.rst

@@ -16,7 +16,7 @@ an event and you want to react to it in your plugin.
 For this you need to:
 
 1. Include openedx-events in your dependencies.
-2. Connect your receiver functions to the signals being sent.
+2. Connect your :term:`receiver <Event Receiver>` functions to the signals being sent.
 
 Connecting signals can be done using regular django syntax:
 
@@ -59,7 +59,7 @@ plugin system.
 Sending events
 ^^^^^^^^^^^^^^
 
-Sending events requires you to import both the event definition as well as the
+Sending events requires you to import both the :term:`event definition <Event Definition>` as well as the
 attr data classes that encapsulate the event data.
 
 .. code-block:: python

docs/quickstarts/use-events-to-call-webhook.rst

@@ -32,9 +32,9 @@ Configuration
 
 The package we just installed is a `Django plugin`_, which adds additional
 configurations to our working environment thanks to the extension mechanisms put in place. Now,
-signal receivers are listening to the registration and enrollment events sent within the LMS service.
+:term:`event receivers <Event Receiver>` are listening to the registration and enrollment events sent within the LMS service.
 
-The following is the implementation for the signal receiver listening for the event ``STUDENT_REGISTRATION_COMPLETED``:
+The following is the implementation for the `event receivers <Event Receiver>` listening for the event ``STUDENT_REGISTRATION_COMPLETED``:
 
 .. code-block:: python
 
@@ -97,7 +97,7 @@ The following is the implementation for the signal receiver listening for the ev
             flatten_dict(zapier_payload),
         )
 
-Those receivers work out of the box after the plugin installation. Now, we must
+Those `event receivers <Event Receiver>` work out of the box after the plugin installation. Now, we must
 set the plugin settings which indicate where to send the events data. For this,
 go to ``env/apps/openedx/settings/development.py`` and add your Zapier configuration:
 
@@ -109,13 +109,13 @@ go to ``env/apps/openedx/settings/development.py`` and add your Zapier configura
 Getting data from Zapier
 ------------------------
 
-Now that you have configured both receivers, you'll need to trigger the events
+Now that you have configured both `event receivers <Event Receiver>`, you'll need to trigger the events
 so you receive the events data in Zapier. Try it out!
 
 .. _openedx-events-2-zapier: https://github.com/eduNEXT/openedx-events-2-zapier
 .. _Tutor: https://github.com/overhangio/tutor
 .. _Django plugin: https://github.com/openedx/edx-django-utils/blob/master/edx_django_utils/plugins/README.rst
 
 .. warning::
-    The receiver function implemented in this tutorial was intended to be lightweight, just to serve as an example for events' receivers. However, in production
+    The `event receiver <Event Receiver>` function implemented in this tutorial was intended to be lightweight, just to serve as an example for event receivers. However, in production
     settings, we encourage the use of asynchronous tasks to avoid creating bottlenecks.

docs/reference/glossary.rst

@@ -0,0 +1,41 @@
+Open edX Events Glossary
+##########################
+
+An event has multiple components that are used to define, trigger, and handle the event. This glossary provides definitions for some of the terms to ease the adoption of the Open edX Events library.
+
+.. glossary::
+
+    Event Receiver
+      An event receiver, handler, or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Since Events are Django-signals, then receivers are registered with the signal dispatcher and are called when the event is emitted. In Django, event receivers are known as signal handlers. Both terms are used interchangeably.
+
+    Event Trigger
+      An event trigger is the action that causes an event to be emitted. When a trigger action occurs, the associated event is emitted, and any registered event receivers are called to handle the event. For example, when a user enrolls in a course, the ``COURSE_ENROLLMENT_CREATED`` event is triggered. In this case, the event trigger is the user enrolling in the course.
+
+    Event Payload
+      The event payload is the data associated with an event that is passed to event receivers when it's triggered. The payload of an event are data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) that carry data about the event such as the event name, timestamp, and any additional metadata and information about the actual event. For more information, see the `Events Payload ADR`_.
+
+    Event Type
+      The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``.
+
+    Event Definition
+      An event is a signal that is emitted when a specific action occurs in the platform. The event definition is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method.
+
+    Event Bus
+      To be added soon.
+
+    Event Bus Producer
+      To be added soon.
+
+    Event Bus Consumer
+      To be added soon.
+
+    Event Bus Topic
+      To be added soon.
+
+    Event Bus Producer Config
+      To be added soon.
+
+    Event Bus Settings
+      To be added soon.
+
+.. _Events Payload ADR: :doc: `/decisions/0003-events-payload`

docs/reference/index.rst

@@ -6,5 +6,6 @@ References
    :caption: Contents:
 
    events
+   glossary
    oeps
    architecture-subdomains