From f71dd8cfaa2b10eed33820823a8d6c5d01d80e9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 23 Dec 2024 23:39:04 -0500 Subject: [PATCH 1/3] 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. --- .../add_link_website_unit_file.rst | 2 +- source/educators/how-tos/preview_content.rst | 36 ++++++ .../view_published_released_content.rst | 36 ++++++ .../content_creation_management.rst | 4 +- .../about_video_guidelines.rst | 16 ++- .../add_video_to_course.rst | 29 +++-- .../course_export_terminology.rst | 8 +- .../exercise_tools/SCORM_overview.rst | 6 +- .../exercise_tools/conditional_module.rst | 10 +- .../exercise_tools/google_docs.rst | 3 +- .../exercise_tools/mathjax_studio.rst | 11 +- .../exercise_tools/text_input.rst | 4 +- .../exercise_tools/text_input_xml.rst | 121 +++++++++--------- .../course_development/files_page.rst | 5 +- .../parent_child_components.rst | 40 ++++-- .../course_development/troubleshoot_video.rst | 14 +- .../work_with_targz_file.rst | 3 +- .../references/testing_course_content.rst | 48 +------ 18 files changed, 236 insertions(+), 160 deletions(-) rename source/educators/{references => how-tos}/course_development/text_components/add_link_website_unit_file.rst (99%) create mode 100644 source/educators/how-tos/preview_content.rst create mode 100644 source/educators/how-tos/view_published_released_content.rst diff --git a/source/educators/references/course_development/text_components/add_link_website_unit_file.rst b/source/educators/how-tos/course_development/text_components/add_link_website_unit_file.rst similarity index 99% rename from source/educators/references/course_development/text_components/add_link_website_unit_file.rst rename to source/educators/how-tos/course_development/text_components/add_link_website_unit_file.rst index e71c43e4f..e99201e13 100644 --- a/source/educators/references/course_development/text_components/add_link_website_unit_file.rst +++ b/source/educators/how-tos/course_development/text_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 new file mode 100644 index 000000000..4796e374c --- /dev/null +++ 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 new file mode 100644 index 000000000..5b93c43b1 --- /dev/null +++ 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 index 64e96aa20..915721992 100644 --- 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 index 4173d0f16..39ba67f5f 100644 --- 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 `. \ No newline at end of file +:ref:`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) \ No newline at end of file diff --git a/source/educators/references/course_development/add_video_to_course.rst b/source/educators/references/course_development/add_video_to_course.rst index 89b2ea522..4ed112876 100644 --- 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,12 +67,7 @@ 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`. @@ -83,3 +75,16 @@ that site. Keep the following guidelines in mind. * 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) \ No newline at end of file diff --git a/source/educators/references/course_development/course_export_terminology.rst b/source/educators/references/course_development/course_export_terminology.rst index 8efeddc45..ca6cd2a2e 100644 --- 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 `_ 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 index 5b4e8875d..d0d0b008d 100644 --- 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 `_ 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/source/educators/references/course_development/exercise_tools/conditional_module.rst b/source/educators/references/course_development/exercise_tools/conditional_module.rst index f43d31374..9cbe7aad9 100644 --- a/source/educators/references/course_development/exercise_tools/conditional_module.rst +++ b/source/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 You see this because "lec27_Q1" was not attempted. - \ No newline at end of file + + +.. seealso:: + :class:dropdown + + :ref: `add_delete_course_tags` (how-to) \ No newline at end of file diff --git a/source/educators/references/course_development/exercise_tools/google_docs.rst b/source/educators/references/course_development/exercise_tools/google_docs.rst index 6d2e2098d..8718545af 100644 --- 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. ********* 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 index b87879a78..03ba3e625 100644 --- 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 `_. MathJax automatically formats +Open edX platform uses `MathJax `_. 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) \ No newline at end of file + :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 index 2477c4209..adc7c80d3 100644 --- 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. ============================= diff --git a/source/educators/references/course_development/exercise_tools/text_input_xml.rst b/source/educators/references/course_development/exercise_tools/text_input_xml.rst index b7de420e0..99c40d7b5 100644 --- a/source/educators/references/course_development/exercise_tools/text_input_xml.rst +++ b/source/educators/references/course_development/exercise_tools/text_input_xml.rst @@ -1,14 +1,12 @@ .. _Text Input Problem XML: -******************************** Text Input Problem XML Reference -******************************** +################################# .. tags:: educator, reference -============== Template -============== +********* .. code-block:: xml @@ -32,9 +30,9 @@ Template -========= + Elements -========= +********* For text input problems, the ```` element can include this hierarchy of child elements. @@ -54,15 +52,15 @@ hierarchy of child elements. In addition, standard HTML tags can be used to format text. ---------------------- + ```` ---------------------- +===================== Required. Indicates that the problem is a text input problem. -^^^^^^^^^^ + Attributes -^^^^^^^^^^ +----------- .. list-table:: :widths: 20 80 @@ -89,9 +87,9 @@ Attributes example, ```` specifies that the problem allows regular expressions and is case sensitive. -^^^^^^^^^^ + Children -^^^^^^^^^^ +--------- * ``