2025-02-24 Educators WG: Educators Docs Updates and Maintenance Onboarding

Recording:

Video: Open edX Educators WG 2025-02-24: Educators Docs Update and Onboarding

Transcript:

Minutes:

(AI Generated and reviewed)

Open Edx Documentation Progress and Collaboration

John discussed the importance of documentation for the Open Edx project, emphasizing its role in adoption, productivity, and maintenance. He highlighted the significant progress made since October last year, when a funded contribution brought together Alice, Neo, Edu Next, and Curricumy to improve the documentation. The number of pages in the Open Edx Docs for educators increased from 40 to over 600, with 30 of them now filled with content. The documents were reorganized using the diataxis framework to make them more user-friendly. John also mentioned the collaboration with the Btr team to align the testing cycle with documentation. He called for the wider Open Edx community to get involved in testing and updating the newly migrated documents to ensure they are fully in line with the latest release.

Testing and Updating Documentation Process

John discussed the importance of testing and submitting changes to the documentation, as well as participating in the upcoming hackathon in March. He demonstrated the process of testing the documentation, using the sandbox version of Open Edx for testing purposes. He emphasized the need for community members to review and update the documentation, particularly the conceptual sections. John also highlighted the need for testing the accuracy of the steps provided in the documentation. He encouraged everyone to use the sandbox version for testing, as it is a clean and up-to-date version of Open Edx.

Updating Documentation and Fixing Issues

John discussed the process of updating and fixing documentation for their course. He explained that when a change is made, it's necessary to update the documentation to reflect the new steps. He also mentioned that if a step is broken, an issue can be raised to fix it. John highlighted the importance of raising issues with detailed instructions on how to recreate the problem. He also mentioned that uploading images to the documentation is not straightforward and suggested that issues could be raised to update outdated images. John then played a video from Anna from Edx, which was a significant part of the presentation.

Editing Open Edx Documents for Hackathon

John explained the process of editing an existing document in the Open Edx Repository for the Hackathon on March 19th. The goal is to update the maintenance chart in each document to include the review date, reviewer or working group (Care working group), release date, and update status. To make these changes, one needs to access their Github account, find the document, and update the maintenance chart. John also emphasized the importance of ensuring all marks are in the correct spot and testing in the appropriate release.

Proposing Documentation Changes on Github

John discussed the process of proposing changes to documentation on Github. He explained that users can create an issue related to the documentation, select a specific template, add a title and description of the issue, and then create the issue. He also demonstrated how to embed a link in the documentation and make edits. John concluded by sharing an example of a simple change he made to a document and encouraged others to participate in the process.

Improving EdX Documentation and Hackathon

John discussed the process of improving the documentation on the EdX platform. He explained that anyone can make changes and submit them for review, with the changes being merged into the actual build. He also mentioned the availability of resources for those interested in making changes, such as documentation on how to make a pull request and create a Github issue. John encouraged everyone to get involved and offered support for those who need it. He also announced a hackathon scheduled for May 19th, where participants can contribute to improving the documentation. The top contributor will receive a prize.

Addressing Documentation and Template Issues

Julie suggested adding an issue to the update page regarding document inconsistencies, which John agreed to. John also mentioned the need for better documentation and the potential for future improvements. Esteban raised a question about the process of choosing a template, which John agreed to investigate. Esteban also brought up the topic of feedback and the possibility of adding a tutorial section. John confirmed that the document Esteban was referring to was outdated and suggested opening an issue to address the gaps in the documentation.

Improving Feedback Process and Hackathon Discussion

Esteban and John discussed improving the friendliness of their feedback process. Esteban suggested implementing a more intuitive form for educators, rather than relying solely on GitHub issues. They also considered adding a tag system to their documents, which would help users find the right information, especially for those whose first language is not English. John agreed to explore these suggestions and mentioned the possibility of introducing a chatbot for better navigation. They also discussed the upcoming hackathon and encouraged everyone to participate.