Jswope00/assimilate legacy docs #561
Conversation
openedx-webhooks
added
the
open-source-contribution
|
Thanks for the pull request, @jswope00! What's next?Please work through the following steps to get your changes ready for engineering review: 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo 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:
🔘 Get a green buildIf 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 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:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
My understanding is our Docs contractor with @feanil added this, but I don't love it. I think it makes it much more confusing/unapproachable to understand from a less-technical person's standpoint when they want to make a change to the docs, because they go to edit content and instead see this symlink. I think it's better to have one page of content (how to log in, for example) and direct link to that. |
| @@ -6,3 +6,4 @@ Community Home | |||
|
|
|||
| release_notes/index | |||
| security_policy/index | |||
| how-tos/receive_announcements_by_email | |||
There was a problem hiding this comment.
Why is this being added here?
| @@ -8,3 +8,4 @@ Educators: Concepts | |||
| :glob: | |||
|
|
|||
| instructional_design/index | |||
There was a problem hiding this comment.
Should we remove this? I think it's empty
| * The **Courses** page provides information about your courses and allows you to change course settings. By | ||
| default, the dashboard opens to the **Courses** page. The **Courses** page on the dashboard now includes two main categories of filters with subcategories in each main category. **Course Status** includes 'In progress,' 'Not Started,' 'Done,' 'Not Enrolled,' and 'Upgraded.' These different filters allow you to filter all of the courses based on the course status. **Sort** includes 'Last enrolled' and 'Title (A-Z).' These filters allow you to filter the course alphabetically or when you were last enrolled in the course. | ||
|
|
||
| * The **Programs** page lists any programs, such as XSeries or MicroMasters programs, that edX offers for courses that you are enrolled in. Programs appear on this page if you are enrolled in any course that is part of that program. This page also shows how many courses in the program you have completed, how many are in progres, and the number of remaining courses you have left in the program. For more information, see :ref:`Explore edX Programs <Explore edX Programs>`. |
There was a problem hiding this comment.
this is edx.org-specific, right? To what extent are you stripping that out at this stage?
…rse into Open edX docs
@sarina I am heading towards this approach for assimilating the legacy edx docs into the Open edX docs. I think the approach fits the current structure of Open edX docs, it has a nice "tracking" system in that docs that are removed from migration_wip are done, and it is easy enough that others can be trained on it.
The process is as follows:
Pages that are obviously EdX.org specific and irrelevant to Open edX (e.g. The edX Partner Portal) can be deleted and excluded from the migration. Pages that are ambiguous should be migrated and we'll make a determination on them later.
Give every document a diataxis tag. You can also use the tag "navigational" if the document only serves a navigational purpose.
Give every document a role tag(s). I haven't done that in these docs yet, but I think it's a good idea.
Add ".. seealso::" links, based on other documents that belong with the one you are editing. This is sometimes related docs from a larger doc that you broke up, and sometimes it is documents from other places that weren't previously attached. Therefore, this requires some critical thinking, knowledge of Open edX, and knowledge of the docs. I suggest in a future phase we revisit these "see also" links with a more systematic approach, once all docs are in the Open edX docs format.
Fix any errors that arise in build. Common ones:
Questions/Issues
I am wary (not worried, just aware of it) we are making the docs less readable and harder to maintain.
Less Readable = Breaking up cohesive docs into pieces and then linking to each other (instead of in one doc). Maybe that is necessary for now, and as we improve we'll strip away unsupported and redundant docs, and get tighter with our "see also" linking.
Harder to Maintain = I find myself creating more absolute references via :doc:. I'll try to use more :ref: in future commits.
What is the function of a "reusable_content" folder? How does it help organization? Isn't everything potentially re-usable? What if we think something won't be re-used, but then it is, or vice versa?