docs: improve explanations

cms/djangoapps/contentstore/docs/decisions/0003-hybrid-approach-for-public-apis.rst

@@ -10,11 +10,8 @@ Reason for rejection
 --------------------
 
 The objectives for public authoring APIs changed from the time this decision was made:
-we are now implementing a limited set of experimental APIs that are intended as an
-MVP for a future, more complete set of APIs. The authoring APIs we are implementing
-are a public set of wrappers around existing functionality, and are not intended to
-be used for production course authoring yet. The responsibility for avoiding conflicts
-and resolving them if they occur is on the user.
+We are now limiting our offering to a set of experimental APIs with which to flesh our what a supported set of APIs might become. As such, the authoring APIs we are now implementing
+are just a public set of wrappers around existing functionality, and are not fit for production course authoring. The responsibility for avoiding conflicts and resolving them, if they occur, is on the user.
 
 Context
 -------

cms/djangoapps/contentstore/docs/decisions/0004-service-layer-for-contentstore-views.rst

@@ -31,8 +31,21 @@ Consequences
 ------------
 - Future view methods should confine business logic to the service layer. This ADR mandates the extraction of business logic from view files into separate entities, without prescribing specific file structures or naming conventions.
 
-Examples
---------
+Example
+-------
+
+The following example shows a refactoring to this service layer pattern.
+
+Before refactoring, the view method implements some view-related logic like
+authorization via `if not has_studio_read_access: ...` and serialization,
+but also business logic: instantiating modulestore, fetching videos from it,
+and then transforming the data to generate a new data structure `usage_locations`.
+
+After refactoring, the view method only implements logic related to the view / API layer,
+and the business logic is extracted to a service file called `videos_provider.py` outside
+the `views` folder. Now the videos provider is responsible for fetching and transforming
+the data, while the view is responsible for authorization and serialization.
+
 
 **Before:**::
 
@@ -50,10 +63,10 @@ Examples
             store = modulestore()
             usage_locations = []
             videos = store.get_items(
-            course_key,
-            qualifiers={
-                    'category': 'video'
-            },
+                course_key,
+                qualifiers={
+                        'category': 'video'
+                },
             )
             for video in videos:
             video_id = getattr(video, 'edx_video_id', '')