Copy editing pass through the descriptive strings.

analytics_data_api/v0/views/learners.py

@@ -28,7 +28,7 @@ from analytics_data_api.v0.views.utils import split_query_argument
 
 class LearnerView(CourseViewMixin, generics.RetrieveAPIView):
     """
-    Get a particular student's data for a particular course.
+    Get data for a particular learner in a particular course.
 
     **Example Request**
 
@@ -36,24 +36,33 @@ class LearnerView(CourseViewMixin, generics.RetrieveAPIView):
 
     **Response Values**
 
-        Returns the learner metadata and engagement data:
+        Returns metadata and engagement data for the learner in JSON format.
 
-            * username: User's username.
-            * enrollment_mode: Enrollment mode (e.g. "honor).
-            * name: User's full name.
-            * email: User's email.
-            * segments: Classification for this course based on engagement, (e.g. "has_potential").
+            * username: The username of the enrolled learner.
+            * enrollment_mode: The learner's selected learning track (for
+              example, "audit" or "verified").
+            * name: The learner's full name.
+            * email: The learner's email address.
+            * segments: Classification, based on engagement, of this learner's
+              work in this course (for example, "highly_engaged" or
+              "struggling").
             * engagements: Summary of engagement events for a time span.
-                * videos_viewed: Number of times a video was played.
-                * problems_completed: Unique number of problems completed.
-                * problems_attempted: Unique number of problems attempted.
-                * discussions_contributed: Number of discussions (e.g. forum posts).
+                * videos_viewed: Number of times any course video was played.
+                * problems_completed: Number of unique problems the learner
+                  answered correctly.
+                * problems_attempted: Number of unique problems attempted.
+                  This is a count of the individual problems the learner
+                  tried. Each problem in a course can increment this count by
+                  a maximum of 1.
+                * discussions_contributed: Number of posts, responses, or
+                  comments the learner contributed to course discussions.
 
     **Parameters**
 
         You can specify the course ID for which you want data.
 
-        course_id -- The course within which user data is requested.
+        course_id -- The course identifier for which user data is requested.
+        For example, edX/DemoX/Demo_Course.
 
     """
     serializer_class = LearnerSerializer
@@ -76,7 +85,7 @@ class LearnerView(CourseViewMixin, generics.RetrieveAPIView):
 
 class LearnerListView(CourseViewMixin, generics.ListAPIView):
     """
-    Get a paginated list of student data for a particular course.
+    Get a paginated list of data for all learners in a course.
 
     **Example Request**
 
@@ -85,55 +94,66 @@ class LearnerListView(CourseViewMixin, generics.ListAPIView):
     **Response Values**
 
         Returns a paginated list of learner metadata and engagement data.
-        Pagination data is returned in the top-level of the returned JSON
-        object:
+        Pagination data is returned in the top level of the returned JSON
+        object.
 
-            * count: The number of learners matching the query.
+            * count: The number of learners that match the query.
             * page: The current one-indexed page number.
             * next: A hyperlink to the next page if one exists, otherwise null.
-            * previous: A hyperlink to the previous page if one exists, otherwise null.
-
-        The 'results' key in the returned JSON object maps to an array of
-        learners which contains at most a full page's worth of learners.  Each
-        learner is a JSON object containing the following keys:
-
-            * username: User's username.
-            * enrollment_mode: Enrollment mode (e.g. "honor).
-            * name: User's full name.
-            * email: User's email.
-            * segments: Classification for this course based on engagement, (e.g. "has_potential").
+            * previous: A hyperlink to the previous page if one exists,
+              otherwise null.
+
+        The 'results' key in the returned object maps to an array of
+        learners that contains, at most, a full page's worth of learners. For
+        each learner there is an object that contains the following keys.
+
+            * username: The username of an enrolled learner.
+            * enrollment_mode: The learner's selected learning track (for
+              example, "audit" or "verified").
+            * name: The learner's full name.
+            * email: The learner's email address.
+            * segments: Classification, based on engagement, of each learner's
+              work in this course (for example, "highly_engaged" or
+              "struggling").
             * engagements: Summary of engagement events for a time span.
-                * videos_viewed: Number of times a video was played.
-                * problems_completed: Unique number of problems completed.
-                * problems_attempted: Unique number of problems attempted.
-                * discussions_contributed: Number of discussions (e.g. forum posts).
+                * videos_viewed: Number of times any course video was played.
+                * problems_completed: Number of unique problems the learner
+                  answered correctly.
+                * problems_attempted: Number of unique problems attempted.
+                  This is a count of the individual problems the learner
+                  tried. Each problem in a course can increment this count by
+                  a maximum of 1.
+                * discussions_contributed: Number of posts, responses, or
+                  comments the learner contributed to course discussions.
 
     **Parameters**
 
-        You can filter the list of learners by course ID and other parameters
-        such as enrollment mode and text search.  You can also control the
-        page size and page number of the response, as well as sort the learners
-        in the response.
-
-        course_id -- The course within which user data is requested.
-        page -- The page of results which should be returned.
-        page_size -- The maximum number of results which should be returned per page.
-        text_search -- A string to search over the name, username, and email of learners.
-        segments -- A comma-separated string of segments to which
-            learners should belong.  Semgents are "OR"-ed together.
-            Cannot use in combination with `ignore_segments`
-            argument.
-        ignore_segments -- A comma-separated string of segments to
-            which learners should NOT belong.  Semgents are "OR"-ed
-            together.  Cannot use in combination with `segments`
-            argument.
+        You can filter the list of learners by course ID and by other
+        parameters, including enrollment mode and text search. You can also
+        control the page size and page number of the response, as well as sort
+        the learners in the response.
+
+        course_id -- The course identifier for which user data is requested.
+            For example, edX/DemoX/Demo_Course.
+        page -- The page of results that should be returned.
+        page_size -- The maximum number of results to return per page.
+        text_search -- An alphanumeric string that is used to search name,
+            username, and email address values to find learners.
+        segments -- A comma-separated list of segment names that is used
+            to select learners. Only learners who are categorized in at least
+            one of the segments are returned. Cannot be used in combination
+            with the `ignore_segments` argument.
+        ignore_segments -- A comma-separated list of segment names that is
+            used to exclude learners. Only learners who are NOT categorized
+            in any of the segments are returned. Cannot be used in combination
+            with the `segments` argument.
         cohort -- The cohort to which all returned learners must
             belong.
-        enrollment_mode -- The enrollment mode to which all returned
+        enrollment_mode -- The learning track to which all returned
             learners must belong.
         order_by -- The field for sorting the response. Defaults to 'username'.
-        sort_order -- The sort direction.  One of 'asc' or 'desc'.
-            Defaults to 'asc'.
+        sort_order -- The sort direction.  One of 'asc' (ascending) or 'desc'
+            (descending). Defaults to 'asc'.
 
     """
     serializer_class = LearnerSerializer
@@ -210,8 +230,8 @@ class LearnerListView(CourseViewMixin, generics.ListAPIView):
 
 class EngagementTimelineView(CourseViewMixin, generics.ListAPIView):
     """
-    Get a particular learner's engagement timeline for a particular course.  Days
-    without data will not be returned.
+    Get a particular learner's engagement timeline for a particular course.
+    Days without data are not returned.
 
     **Example Request**
 
@@ -219,20 +239,26 @@ class EngagementTimelineView(CourseViewMixin, generics.ListAPIView):
 
     **Response Values**
 
-        Returns the engagement timeline.
-
-            * days: Array of the learner's daily engagement timeline.
-                * problems_attempted: Unique number of unique problems attempted.
-                * problems_completed: Unique number of problems completed.
-                * discussions_contributed: Number of discussions participated in (e.g. forum posts)
-                * videos_viewed: Number of videos watched.
+        Returns the engagement timeline in an array.
+
+            * days: An array of the learner's daily engagement timeline.
+                * problems_attempted: Number of unique problems attempted.
+                  This is a count of the individual problems the learner
+                  tried. Each problem in a course can increment this count by
+                  a maximum of 1.
+                * problems_completed: Number of unique problems the learner
+                  answered correctly.
+                * discussions_contributed: Number of posts, responses, or
+                  comments the learner contributed to course discussions.
+                * videos_viewed: Number of times any course video was played.
                 * problem_attempts_per_completed: TBD
 
     **Parameters**
 
-        You can specify course ID for which you want data.
+        You can specify the course ID for which you want data.
 
-        course_id -- The course within which user data is requested.
+        course_id -- The course identifier for which user data is requested.
+        For example, edX/DemoX/Demo_Course.
 
     """
     serializer_class = EngagementDaySerializer
@@ -258,8 +284,8 @@ class EngagementTimelineView(CourseViewMixin, generics.ListAPIView):
 
 class CourseLearnerMetadata(CourseViewMixin, generics.RetrieveAPIView):
     """
-    Get metadata on learners within a course. Includes data on segments,
-    cohorts, enrollment modes, and an engagement rubric.
+    Get metadata about the learners in a course. Includes data on segments,
+    cohorts, and enrollment modes. Also includes an engagement rubric.
 
     **Example Request**
 
@@ -267,33 +293,33 @@ class CourseLearnerMetadata(CourseViewMixin, generics.RetrieveAPIView):
 
     **Response Values**
 
-        Returns a JSON object with the following keys:
+        Returns an object with the following keys.
 
-            * cohorts: An object mapping the names of cohorts in the course to
-              the number of students belonging to those cohorts.
-            * segments: An object mapping the names of segments in the course
-              to the number of students belonging to those segments.  The
-              current set of segments are: "highly_engaged", "disengaging",
+            * cohorts: An object that maps the names of cohorts in the course
+              to the number of learners belonging to those cohorts.
+            * segments: An object that maps the names of segments in the course
+              to the number of learners belonging to those segments. The
+              current set of segments is "highly_engaged", "disengaging",
               "struggling", "inactive", and "unenrolled".
-            * enrollment_modes: An object mapping the names of enrollment modes
-              in the course to the number of students belonging to those
-              enrollment modes.  Examples include "honor" and "verified".
+            * enrollment_modes: An object that maps the names of learning
+              tracks in the course to the number of learners belonging to those
+              tracks. Examples include "audit" and "verified".
             * engagement_ranges: An object containing ranges of learner
               engagement with the courseware. Each range has 'below_average',
-              'average', and 'above_average' keys which map to two-element
-              arrays of which the first element is the lower bound (inclusive)
-              and the second element is the upper bound (exclusive).  It has
-              the following keys:
-                * date_range: The time duration for which this data applies
-                * problems_attempted: engagement ranges for the number of
-                  problems attempted in the date range.
-                * problems_completed: engagement ranges for the number of
-                  problems completed in the date range.
-                * problem_attempts_per_completed: engagement ranges for the
+              'average', and 'above_average' keys. These keys map to
+              two-element arrays, in which the first element is the lower bound
+              (inclusive) and the second element is the upper bound
+              (exclusive). It has the following keys.
+                * date_range: The time period to which this data applies.
+                * problems_attempted: Engagement ranges for the number of
+                  unique problems tried in the date range.
+                * problems_completed: Engagement ranges for the number of
+                  unique problems answered correctly in the date range.
+                * problem_attempts_per_completed: Engagement ranges for the
                   number of problem attempts per completed problem in the date
                   range.
-                * discussions_contributed: engagement ranges for the number of
-                  discussions contributed in the date range.
+                * discussions_contributed: Engagement ranges for the number of
+                  times learners participated in discussions in the date range.
 
     """
     serializer_class = CourseLearnerMetadataSerializer