docs: address PR reviews

openedx · Apr 5, 2023 · 2aa0e05 · 2aa0e05
1 parent c269620
commit 2aa0e05
Show file tree

Hide file tree

Showing 7 changed files with 11 additions and 5 deletions.
diff --git a/docs/concepts/hooks-extension-framework.rst b/docs/concepts/hooks-extension-framework.rst
@@ -30,7 +30,7 @@ to migrate to newer open releases with very little to no development effort. In
 the case of the events, this is detailed in the `versioning ADR`_ and the
 `payload ADR`_.
 
-A longer description of the framework and it's history can be found in `OEP 50`_.
+A longer description of the framework and its history can be found in `OEP 50`_.
 
 .. _OEP 50: https://open-edx-proposals.readthedocs.io/en/latest/oep-0050-hooks-extension-framework.html
 .. _versioning ADR: https://github.com/eduNEXT/openedx-events/blob/main/docs/decisions/0002-events-naming-and-versioning.rst

diff --git a/docs/decisions/0003-events-payload.rst b/docs/decisions/0003-events-payload.rst
@@ -14,7 +14,7 @@ Given their public promise status, event hooks have maintainability as the main
 design goal. The contracts we are creating here should be stable enough to
 support the growth of the extensions community. That said, things should be
 allowed to evolve in a backwards compatible manner. When things inevitable break,
-they should break in CI. Which should not require the code of The Open edX platform to
+they should break in CI. Which should not require the code of the Open edX platform to
 test integrations.
 
 

diff --git a/docs/how-tos/adding-events-to-a-service.rst b/docs/how-tos/adding-events-to-a-service.rst
@@ -1,7 +1,7 @@
 How to add an Open edX Event to a service
 =========================================
 
-The next step after creating your first event in the Open edX Events library, it's to trigger the event in the service
+The next step after creating your first event in the Open edX Events library is to trigger the event in the service
 you implemented it for. Here is a checklist of what we've done so far when including a new event to a service:
 
 - Add the openedx-events library to the service project.

diff --git a/docs/how-tos/creating-new-events.rst b/docs/how-tos/creating-new-events.rst
@@ -12,6 +12,10 @@ When creating a new event, you must justify its implementation. For example, you
 send a message through slack or open a new issue in the library repository listing your use cases for it. Or even,
 if you have time, you could accompany your proposal with the implementation of the event to illustrate its behavior.
 
+.. note::
+    There is an open discussion about whether organization scoped events would also exist in openedx-events,
+    in which case this step would be optional. See issue `Organization scoped events <https://github.com/openedx/openedx-events/issues/196>`_.
+
 2. Place your event in an architecture subdomain
 -------------------------------------------------
 
@@ -26,7 +30,7 @@ For those reasons, after studying your new event purpose, you must place it in o
 +-------------------+----------------------------------------------------------------------------------------------------+
 | Subdomain name    | Description                                                                                        |
 +===================+====================================================================================================+
-| Course Authoring  | Allows educators to create, modify, package, annotate (tag), and share learning content.           |
+| Content Authoring  | Allows educators to create, modify, package, annotate (tag), and share learning content.          |
 +-------------------+----------------------------------------------------------------------------------------------------+
 | Learning          | Allows learners to consume content and perform actions in a learning activity on the platform.     |
 +-------------------+----------------------------------------------------------------------------------------------------+

diff --git a/docs/quickstarts/index.rst b/docs/quickstarts/index.rst
@@ -6,4 +6,3 @@ Quickstarts
    :caption: Contents:
 
    use-events-to-call-webhook
-   event-bus
diff --git a/docs/quickstarts/use-events-to-call-webhook.rst b/docs/quickstarts/use-events-to-call-webhook.rst
@@ -89,6 +89,9 @@ The following is the implementation for the signal receiver listening for the ev
             "user": user_info,
             "event_metadata": event_metadata,
         }
+        # 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, you must use asynchronous tasks
+        #  to avoid creating bottlenecks if you wish for others to use your implementation.
         requests.post(
             settings.ZAPIER_REGISTRATION_WEBHOOK,
             flatten_dict(zapier_payload),

diff --git a/docs/reference/achitecture-subdomains.rst → docs/reference/architecture-subdomains.rst b/docs/reference/achitecture-subdomains.rst → docs/reference/architecture-subdomains.rst