FC-0068 docs: concept cleaning by edunext #11 #716

BryanttV · 2024-12-31T16:09:52Z

This PR modifies a series of concept documents migrated from the legacy repositories to the educators' documentation.

openedx-webhooks · 2024-12-31T16:09:57Z

Thanks for the pull request, @BryanttV!

What's next?

Please work through the following steps to get your changes ready for engineering review:

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Let us know that your PR is ready for review:

Who will review my changes?

This repository is currently maintained by @openedx/docs-openedx-org-maintainers. Tag them in a comment and let them know that your changes are ready for review.

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

sarina · 2025-01-06T13:27:23Z

@BryanttV is this ready for review?

BryanttV · 2025-01-07T19:11:36Z

Hi @sarina, yeah, this is ready. Thanks!

sarina

I only reviewed the first file. Please take a look through my comments, and update following documents appropriately before requesting a re-review. Particularly, "Open edX" should be used as an adjective, should not be capitalized as "Open Edx", and some judgement should be applied when to use something like "your Open edX instance" or simply "your instance".

source/educators/concepts/advanced_features/lti_reuse_content.rst

source/educators/concepts/advanced_features/teams_learner_experience.rst

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

Apgomeznext · 2025-01-07T23:32:33Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

-   If you include a staff assessment step, it should be the final step in the
-   assignment.
+   assessment steps. If you include both peer and self assessment steps, Open
+   edX recommends that you place the peer assessment before the self


Replace Open edX as the subject with Open edX Community.

I would actually say, "... self assessment steps, it is recommended that you place..."

Updated: c87cb85

sarina · 2025-01-08T22:58:58Z

source/educators/concepts/advanced_features/using_openedx_as_LTI_provider.rst

+ :ref:`Example: edX as an LTI Provider to Blackboard<edX as an LTI Provider to Blackboard>` (reference)
+
+ :ref: `edX as an LTI Provider to Canvas` (reference)


Where is this reference and why is it not Open edX?

This reference is the Open edX repository, but the tag name of that file wasn't modified to prevent the broken links.

I updated the references to use the correct tags: 4daafbe. Thanks!

sarina · 2025-01-08T23:02:22Z

source/educators/concepts/advanced_features/using_openedx_as_LTI_provider.rst

-near real time. It can take a few moments to complete this exchange for a
-single problem component, and up to several minutes to return aggregated scores
-of all of the problems in a unit or subsection.
+When you include the problem components in a graded Open edX subsection in an


I would rewrite this paragraph because it is confusing, it talks about "Open edX" as a thing when really it needs to be discussing your specific Open edX instance.

When you include problem components from a graded subsection in your Open edX instance in an external LMS, your Open edX instance will grade the learner responses to those problems. Your instance then transfers the learner scores back to the external LMS. This exchange between an external LMS, your Open edX instance, and the external LMS again is near real time. It can take a few moments to complete this exchange for a single problem component, and up to several minutes to return aggregated scores of all the problems in a unit or subsection.

Thanks!, I applied your suggestion: 1d2621d

sarina · 2025-01-08T23:02:41Z

source/educators/concepts/advanced_features/using_openedx_as_LTI_provider.rst


-When you include edX problem components in an external LMS, note the following
-requirements.
+When you include Open edX problem components in an external LMS, note the


Suggested change

When you include Open edX problem components in an external LMS, note the

When you include problem components from your Open edX instance in an external LMS, note the

Updated: 1d2621d

sarina · 2025-01-08T23:03:05Z

source/educators/concepts/advanced_features/using_openedx_as_LTI_provider.rst


-* The edX problem component must be in one of the graded subsections in your
-  course.
+* The Open edX problem component must be in one of the graded subsections in


Suggested change

* The Open edX problem component must be in one of the graded subsections in

* The problem component must be in one of the graded subsections in

Updated: 1d2621d

sarina · 2025-01-08T23:03:11Z

source/educators/concepts/advanced_features/using_openedx_as_LTI_provider.rst

+ :ref: `edX as an LTI Provider to Canvas` (reference)
+
+ :ref: `edX as an LTI Provider to Blackboard` (reference)


I updated the references to use the correct tags: 4daafbe. Thanks!

sarina · 2025-01-08T23:04:50Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

-   recommends that you make ORA assignments count towards only a small
-   percentage of a course's final grade.
+.. note:: Given the high level of subjectivity in peer assessments, the Open
+   edX Community recommends that you make ORA assignments count towards only a


Suggested change

edX Community recommends that you make ORA assignments count towards only a

it is recommended that you make ORA assignments count towards only a

Updated: c87cb85

sarina · 2025-01-08T23:05:06Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

@@ -555,8 +539,8 @@ assignment.
 You can allow the **Top Responses** section to show between 1 and 100
 responses. Keep in mind, however, that each response might be up to 300 pixels
 in height in the list. (For longer responses, learners can scroll to see the
-entire response.) EdX recommends that you specify 20 or fewer responses to
-prevent the page from becoming too long.
+entire response.) The Open edX Community recommends that you specify 20 or


Suggested change

entire response.) The Open edX Community recommends that you specify 20 or

entire response.) It is recommended that you specify 20 or

Updated: c87cb85

sarina · 2025-01-08T23:05:18Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

@@ -586,12 +568,12 @@ correct or incorrect answers to questions.
 .. note:: Do not add more than one ORA component in a course unit. Multiple ORA
   assignments in a unit cause errors when learners submit their assessments.

-EdX suggests that you follow the guidelines and best practices in the
-following sections when you use open response assessments in your courses.
+The Open edX Community suggests that you follow the guidelines and best


Suggested change

The Open edX Community suggests that you follow the guidelines and best

It is suggested that you follow the guidelines and best

Updated: c87cb85

sarina · 2025-01-08T23:06:08Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

-maintained by the development operations team at edX, and are subject to
-change.
+Learners cannot upload file types with the following file name extensions as
+part of and Open Response Assessment. When you define a set of custom file


Suggested change

part of and Open Response Assessment. When you define a set of custom file

part of an Open Response Assessment. When you define a set of custom file

Updated: c87cb85

sarina · 2025-01-08T23:07:00Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

+part of and Open Response Assessment. When you define a set of custom file
+types for learners to upload with their responses, you cannot specify them. The
+extensions on this list are selected and maintained by the development
+operations team at the Open edX Community and are subject to change.


This isn't true, there isn't a development operations team within the community. I'm not sure how this list is defined or maintained so I would simply remove this entire last sentence.

Updated: c87cb85

sarina · 2025-01-10T16:30:36Z

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst

-a set of custom file types for learners to upload with their responses, you
-cannot specify these file types. The extensions on this list are selected and
-maintained by the development operations team at edX, and are subject to
-change.


Please only remove the last sentence ("The extensions on this list are selected and
maintained by the development operations team at edX, and are subject to
change."), not the whole paragraph.

Done: 72a1b1d

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Dec 31, 2024

BryanttV force-pushed the bav/educators_documentation_review_edunext_12 branch from 4099749 to 6d08a6c Compare December 31, 2024 16:42

BryanttV changed the title ~~FC-0068 docs: Concept cleaning by edunext #11~~ FC-0068 docs: concept cleaning by edunext #11 Dec 31, 2024

BryanttV force-pushed the bav/educators_documentation_review_edunext_12 branch from 6d08a6c to 1a9439b Compare December 31, 2024 18:51

mphilbrick211 added the FC Relates to an Axim Funded Contribution project label Jan 2, 2025

BryanttV requested a review from sarina January 7, 2025 19:11

sarina requested changes Jan 7, 2025

View reviewed changes

Apgomeznext reviewed Jan 7, 2025

View reviewed changes

source/educators/concepts/advanced_features/teams_learner_experience.rst Outdated Show resolved Hide resolved

Apgomeznext reviewed Jan 7, 2025

View reviewed changes

source/educators/concepts/exercise_tools/OpenResponseAssessments.rst Show resolved Hide resolved

Apgomeznext reviewed Jan 7, 2025

View reviewed changes

BryanttV added 10 commits January 8, 2025 17:42

docs: update 'using_openedx_as_LTI_provider.rst' file

c93aca2

docs: update 'lti_reuse_content.rst' file

4ed0610

docs: update 'teams_overview.rst' file

0a04b62

docs: update 'managing_teams_discussions.rst' file

a9c2648

docs: update 'teams_learner_experience.rst' file

5a74d8d

docs: update 'drag_and_drop.rst' file

8839aaf

docs: update 'external_graders.rst' file

631efb0

docs: update 'create_exercises.rst' file

9c7990b

docs: update 'OpenResponseAssessments.rst' file

5551fc8

chore: address PR review

9eac14c

BryanttV force-pushed the bav/educators_documentation_review_edunext_12 branch from f7fe914 to 9eac14c Compare January 8, 2025 22:43

sarina requested changes Jan 8, 2025

View reviewed changes

BryanttV added 2 commits January 9, 2025 11:13

docs: update refs of 'using_openedx_as_LTI_provider.rst' file

4daafbe

docs: rewrite paragraph

1d2621d

BryanttV force-pushed the bav/educators_documentation_review_edunext_12 branch from d88c241 to 1d2621d Compare January 9, 2025 16:28

BryanttV added 2 commits January 9, 2025 12:28

docs: replace 'Open edX Community'

c87cb85

docs: update refs of 'OpenResponseAssessments.rst' file

637ea0a

chore: replace :doc: by :ref:

94b57dc

BryanttV requested review from Apgomeznext and sarina January 9, 2025 18:04

sarina reviewed Jan 10, 2025

View reviewed changes

docs: add deleted paragraph about prohibited file extensions

72a1b1d

BryanttV requested a review from sarina January 10, 2025 17:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FC-0068 docs: concept cleaning by edunext #11 #716

FC-0068 docs: concept cleaning by edunext #11 #716

BryanttV commented Dec 31, 2024

openedx-webhooks commented Dec 31, 2024

sarina commented Jan 6, 2025

BryanttV commented Jan 7, 2025

sarina left a comment

Apgomeznext Jan 7, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

Apgomeznext Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025 •

edited

Loading

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025 •

edited

Loading

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 8, 2025

BryanttV Jan 9, 2025

sarina Jan 10, 2025

BryanttV Jan 10, 2025

		:ref:`Example: edX as an LTI Provider to Blackboard<edX as an LTI Provider to Blackboard>` (reference)

		:ref: `edX as an LTI Provider to Canvas` (reference)

	When you include Open edX problem components in an external LMS, note the
	When you include problem components from your Open edX instance in an external LMS, note the

	* The Open edX problem component must be in one of the graded subsections in
	* The problem component must be in one of the graded subsections in

		:ref: `edX as an LTI Provider to Canvas` (reference)

		:ref: `edX as an LTI Provider to Blackboard` (reference)

	edX Community recommends that you make ORA assignments count towards only a
	it is recommended that you make ORA assignments count towards only a

	entire response.) The Open edX Community recommends that you specify 20 or
	entire response.) It is recommended that you specify 20 or

	The Open edX Community suggests that you follow the guidelines and best
	It is suggested that you follow the guidelines and best

	part of and Open Response Assessment. When you define a set of custom file
	part of an Open Response Assessment. When you define a set of custom file

FC-0068 docs: concept cleaning by edunext #11 #716

Are you sure you want to change the base?

FC-0068 docs: concept cleaning by edunext #11 #716

Conversation

BryanttV commented Dec 31, 2024

openedx-webhooks commented Dec 31, 2024

What's next?

🔘 Get product approval

🔘 Provide context

🔘 Get a green build

🔘 Let us know that your PR is ready for review:

Who will review my changes?

Where can I find more information?

When can I expect my changes to be merged?

sarina commented Jan 6, 2025

BryanttV commented Jan 7, 2025

sarina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BryanttV Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BryanttV Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BryanttV Jan 9, 2025 •

edited

Loading

BryanttV Jan 9, 2025 •

edited

Loading