Merge pull request #15240 from edx/robrap/LEARNER-1101-best-practices

LEARNER-1101: Add best practice doc for course overview/course blocks.

docs/best_practices.rst

+#######################################
+edx-platform Development Best Practices
+#######################################
+
+There are many general best practices documented for `Open edX Development in
+Confluence`_. The following best-practices are specific to edx-platform.
+
+Course Access in LMS
+********************
+
+the following technologies can be used to access course-related data:
+
+* `Course Overviews`_:  Provide performant access to course metadata.
+
+* `Course Blocks`_: Provide performant access to the blocks in a course,
+  including filtering and access control capabilities.
+
+* `Modulestore`_ - Contains all course related data, including course metadata
+  course blocks, and student module data. Course Overviews and Course Blocks are
+  cached performant versions of a subset of this source data.
+
+When coding in the LMS, it is generally preferred to use `Course Overviews`_ and
+`Course Blocks`_, due to the following benefits:
+
+1. Cached versions of course data that are better optimized for Learners.
+
+2. A start of the separation of LMS and Studio data to move us closer to the
+   ultimate ability to separate the two.
+
+**Note**: At this time, these preferred methods are for coding in the LMS, but
+   outside of the courseware.  Inside the courseware, there is more work to be
+   done to take advantage of these techniques.
+
+Prefer using `Course Overviews`_ where possible when you just need course
+metadata, rather than loading the full course. For example, this could be done
+by calling ``get_course_overview_with_access()`` in place of
+``get_course_with_access``. If the course overview doesn't contain the data you
+need, you should consider whether it makes sense to expand what is available via
+the course overview. See an `example use of course overviews`_ in the course
+outline feature.
+
+Prefer using `Course Blocks`_ over loading a full course directly from the
+`modulestore`_. The following is an `example of using course blocks`_ in the
+course outline feature.
+
+If you need to load student user data to combine with the data you retrieve from
+the `Course Blocks`_, you can load the student module data from the modulestore
+without loading the full course. Here is an `example loading the student module
+data`_ in the course outline feature.
+
+.. _Open edX Development in Confluence: https://openedx.atlassian.net/wiki/display/OpenDev/Open+edX+Development
+.. _Course Overviews: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/content/course_overviews/__init__.py
+.. _example use of course overviews: https://github.com/edx/edx-platform/blob/f81c21902eb0e8d026612b052557142ce1527153/openedx/features/course_experience/views/course_outline.py#L26
+.. _Course Blocks: https://openedx.atlassian.net/wiki/display/EDUCATOR/Course+Blocks
+.. _modulestore: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/modulestores/index.html
+.. _example of using course blocks: https://github.com/edx/edx-platform/blob/f81c21902eb0e8d026612b052557142ce1527153/openedx/features/course_experience/utils.py#L65-L72
+.. _example loading the student module data: https://github.com/edx/edx-platform/blob/f81c21902eb0e8d026612b052557142ce1527153/openedx/features/course_experience/utils.py#L49