FC-0068 docs: Reference cleaning by edunext #7 (#710)

* FC-0068 docs: Reference cleaning by edunext #7 This PR modifies a series of reference documents migrated from the legacy repositories to the educators' documentation. The principal changes are in the add_link_website_unit_file, which was modified to be a how-to and create two how-tos based on testing_course_content. * fix commit * Apply suggestions from code review --------- Co-authored-by: Sarina Canelake <[email protected]>
openedx · Jan 6, 2025 · 99e72a3 · 99e72a3
1 parent 1857c3a
commit 99e72a3
Show file tree

Hide file tree

Showing 18 changed files with 236 additions and 162 deletions.
diff --git a/...components/add_link_website_unit_file.rst → ...components/add_link_website_unit_file.rst b/...components/add_link_website_unit_file.rst → ...components/add_link_website_unit_file.rst
@@ -4,7 +4,7 @@
 Add Link to Website, Course Unit, or a File
 #############################################
 
-.. tags:: educator, reference
+.. tags:: educator, how-to
 
 .. _Add a Link in a Text Component:
 

diff --git a/source/educators/how-tos/preview_content.rst b/source/educators/how-tos/preview_content.rst
@@ -0,0 +1,36 @@
+.. _Preview Draft Content:
+
+Preview Draft Content
+#######################
+
+.. tags:: educator, how-to
+
+To preview draft content and see how it would appear to members of different
+groups when it is released, follow these steps.
+
+#. From a unit page in the **Course Outline** in Studio, select **Preview**.
+
+   A separate browser tab opens for the course in the LMS.
+
+#. In the LMS, select one of the **View this course as** options, as described
+   in :ref:`Roles for Viewing Course Content`.
+
+The course view refreshes to present course content as it is currently
+configured in Studio, and as a learner in the selected group would see it.
+
+.. note:: If you use randomized content blocks in your course, you cannot
+   preview unpublished units that contain content from randomized content
+   blocks, because the randomized content is not assigned until after the unit
+   is published. For information about viewing the actual content that has
+   been assigned to a particular learner from a randomized content block in a
+   live course, see :ref:`Specific Student View`.
+
+.. seealso::
+ :class:dropdown
+
+ :ref:`Testing Your Course Content` (reference)
+
+ :ref:`Roles for Viewing Course Content` (reference)
+
+ :ref:`How to View Published and Released Content` (how-to)
+
diff --git a/source/educators/how-tos/view_published_released_content.rst b/source/educators/how-tos/view_published_released_content.rst
@@ -0,0 +1,36 @@
+.. _How to View Published and Released Content:
+
+How to View Published and Released Content
+###########################################
+
+.. tags:: educator, how-to
+
+.. note:: Click here to learn more about :ref:`View Published Content`.
+
+To view published and released content as it would appear to members of
+different groups, follow these steps.
+
+#. From the Studio **Course Outline** page, select **View Live**.
+   Alternatively, from a unit page, select **View Live Version**.
+
+   A separate browser tab opens for the course in the LMS.
+
+#. In the LMS, select one of the **View this course as** options, as described
+   in :ref:`Roles for Viewing Course Content`.
+
+The course view refreshes to present published course content as a learner in
+the selected group would see it.
+
+For more information about each view, see :ref:`Staff View`, :ref:`Student
+View`, or :ref:`Specific Student View`. For more information about viewing
+cohort-specific course content, see :ref:`Viewing Cohort Specific Courseware`.
+
+
+.. seealso::
+ :class:dropdown
+
+ :ref:`Testing Your Course Content` (reference)
+
+ :ref:`Roles for Viewing Course Content` (reference)
+
+ :ref:`Preview Draft Content` (how-to)
diff --git a/source/educators/navigation/content_creation_management.rst b/source/educators/navigation/content_creation_management.rst
@@ -48,7 +48,7 @@ Add Text Components
    ../references/course_development/text_components/text_components.rst
    ../how-tos/course_development/text_components/work_with_html.rst
    ../how-tos/course_development/text_components/create_text_component.rst
-   ../references/course_development/text_components/add_link_website_unit_file.rst
+   ../how-tos/course_development/text_components/add_link_website_unit_file.rst
    ../how-tos/course_development/text_components/add_image.rst
    ../how-tos/course_development/exercise_tools/create_full_screen_image.rst
    ../how-tos/course_development/text_components/paste_without_formatting.rst
@@ -194,6 +194,8 @@ Test Your Course
 
    ../references/testing_course_content.rst
    ../references/roles_for_viewing.rst
+   ../how-tos/view_published_released_content.rst
+   ../how-tos/preview_content.rst
 
 Embed IFrames
 *******************************************************

diff --git a/source/educators/references/course_development/about_video_guidelines.rst b/source/educators/references/course_development/about_video_guidelines.rst
@@ -1,8 +1,7 @@
 .. _Course About Video Guidelines:
 
-********************************
 Course About Video Guidelines
-********************************
+##############################
 
 .. tags:: educator, reference
 
@@ -37,4 +36,15 @@ as your course content videos.
 
 
 For information about how to add an About video to your course About page, see
-:ref:`Add an About Video <Add an About Video>`.
+:ref:`Add an About Video <Add an About Video>`.
+
+.. seealso::
+ :class:dropdown
+
+ :ref:`Introduction to Video` (reference)
+
+ :ref:`Add an About Video` (how-to)
+
+ :ref:`Course and Program Images and Videos` (reference)
+
+ :ref:`Additional Video Options` (how-to)
diff --git a/source/educators/references/course_development/add_video_to_course.rst b/source/educators/references/course_development/add_video_to_course.rst
@@ -1,8 +1,7 @@
 .. _Introduction to Video:
 
-************************
 Introduction to Video
-************************
+#########################
 
 .. tags:: educator, reference
 
@@ -28,9 +27,8 @@ For more information about how learners can interact with course videos, see
 
 .. _Working with Video Components:
 
-#############################
 Working with Video Components
-#############################
+******************************
 
 You use video components to add videos to your course in Studio. In video
 components, you add the name and location of your video, as well as the video
@@ -46,9 +44,8 @@ Video Options`.
 
 .. _Adding a Video to a Course:
 
-##########################
 Adding a Video to a Course
-##########################
+**************************
 
 To make a video visible in your course, you create a video component in a Unit
 in Studio, and then you add information for the video to the video component.
@@ -70,16 +67,24 @@ that site. Keep the following guidelines in mind.
   you upload on sites such as Vimeo, Dailymotion, or other sites that use their
   own player.
 
-  To help make sure all standard browsers can play your video, edX strongly
-  recommends that you use .mp4 format.
-
-  The video URL might resemble the following example.
-
-  ``https://s3.amazonaws.com/edx-course-videos/edx-edx101/EDXSPCPJSP13-G030300.mp4``
+  To ensure that all standard browsers can play your video, you should use the .mp4 format.
 
 * If you have copies of a video in multiple resolutions, you must upload each
   copy to the hosting site. For more information, see :ref:`Video Guidelines`.
 
 * After you upload a video on a hosting site, you must make sure you have the
   URL for that copy of the video. If you upload copies of your video on more
   than one hosting site, make sure you have the URL for each video location.
+
+.. seealso::
+ :class:dropdown
+
+ :ref:`Course About Video Guidelines` (reference)
+
+ :ref:`Add an About Video` (how-to)
+
+ :ref:`Course and Program Images and Videos` (reference)
+
+ :ref:`Additional Video Options` (how-to)
+
+ :ref:`Troubleshoot Videos` (reference)
diff --git a/source/educators/references/course_development/course_export_terminology.rst b/source/educators/references/course_development/course_export_terminology.rst
@@ -1,8 +1,7 @@
 .. _Course Export File Terminology:
 
-********************************************
 Course Outline Terminology in Exported Files
-********************************************
+#############################################
 
 .. tags:: educator, reference
 
@@ -31,11 +30,6 @@ For example, if you want to find a specific section in your course when you
 open the list of files that your course contains, look in the **Chapter**
 directory. To find a unit, look in the **Vertical** directory.
 
-.. only:: Partners
-
-  For more information, see `course_structure <course_structure_research_guide>`_ in the **EdX
-  Research Guide**.
-
 .. seealso::
  :class: dropdown
 

diff --git a/source/educators/references/course_development/exercise_tools/SCORM_overview.rst b/source/educators/references/course_development/exercise_tools/SCORM_overview.rst
@@ -1,12 +1,15 @@
 .. _SCORM Overview:
 
+SCORM Overview
+###############
+
 ********
 Overview
 ********
 
 .. tags:: educator, reference
 
-The SCORM `XBlock <https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/overview/introduction.html>`_ provides the ability to display SCORM content within the Open edX LMS and Studio.
+The :ref:`SCORM XBlock` provides the ability to display SCORM content within the Open edX LMS and Studio.
 It can save a learners state and report scores to the progress tab of the course.
 It currently supports SCORM 1.2 and SCORM 2004 standard.
 
@@ -26,7 +29,6 @@ Try to limit the SCORM package to 1 quiz or scored component.
 Technical information
 *********************
 
-
 There are 2 events a SCORM package can emit in order to communicate with the Open edX platform.
 
 * For a SCORM module to set the Unit as complete (trigger the completion event of Open edX), the following event needs to be emitted:

diff --git a/...e/educators/references/course_development/exercise_tools/conditional_module.rst b/...e/educators/references/course_development/exercise_tools/conditional_module.rst
@@ -1,8 +1,7 @@
 .. _Conditional Module:
 
-##################
 Conditional Module
-##################
+###################
 
 .. tags:: educator, reference
 
@@ -96,4 +95,9 @@ Examples of conditional depends on problem
     </conditional>
     <conditional sources="i4x://MITx/0.000x/problem/Conditional:lec27_Q1" attempted="False">
         <html display_name="HTML for not attempted problem">You see this because "lec27_Q1" was not attempted.</html>
-    </conditional>
+    </conditional>
+
+.. seealso::
+ :class:dropdown
+
+ :ref: `add_delete_course_tags` (how-to)
diff --git a/source/educators/references/course_development/exercise_tools/google_docs.rst b/source/educators/references/course_development/exercise_tools/google_docs.rst
@@ -24,8 +24,7 @@ body. For more information, see :ref:`Google Calendar Tool`.
 .. note:: Google services are not available in some regions and countries. If
   Google services are not available in a learner's area, the learner might see
   an "image unavailable" message in the place of the Google Drive file or
-  calendar. EdX strongly suggests that you provide alternative resources for
-  learners in these areas.
+  calendar.  It is recommended that you provide alternative resources for learners in these areas.
 
 *********
 Overview

diff --git a/source/educators/references/course_development/exercise_tools/mathjax_studio.rst b/source/educators/references/course_development/exercise_tools/mathjax_studio.rst
@@ -1,13 +1,12 @@
 .. _MathJax in Studio:
 
-##############################
 MathJax for Mathematics
 ##############################
 
 .. tags:: educator, reference
 
 To produce clear and professional-looking symbols and equations in web browser,
-edX uses `MathJax <https://www.mathjax.org/>`_. MathJax automatically formats
+the Open edX platform uses `MathJax <https://www.mathjax.org/>`_. MathJax automatically formats
 the mathematical symbols and equations that you enter in Text and problem
 components using LaTeX notation into beautiful math.
 
@@ -45,4 +44,10 @@ For display equations, you can do either of the following.
 .. seealso::
  :class: dropdown
 
- :ref:`Adding MathJax` (reference)
+ :ref:`Adding MathJax` (reference)
+
+ :ref:`Math Expression Input` (reference)
+
+ :ref:`Math Expression Input Problem XML` (reference)
+
+ :ref:`Adding MathJax` (how-to)
diff --git a/source/educators/references/course_development/exercise_tools/text_input.rst b/source/educators/references/course_development/exercise_tools/text_input.rst
@@ -25,8 +25,8 @@ Overview
 In text input problems, learners enter text into a response field. The
 response can include numbers, letters, and special characters such as
 punctuation marks. Because the text that the learner enters must match the
-instructor's specified answer exactly, including spelling and punctuation, edX
-recommends that you specify more than one correct answer for text input
+instructor's specified answer exactly, including spelling and punctuation, it is
+recommend that you specify more than one correct answer for text input
 problems to allow for differences in capitalization and typographical errors.
 
 =============================