2026-02-04 Docs WG meeting
All public Working Group meetings follow the Recording Policy for Open edX Meetings
Date
Feb 4, 2026
Participants
@Sarina Canelake
@Brian Smith
@Ahmed Khalid
@John Swope
@AnaP Gómez
AI Summary (Gemini, edited)
The Documentation Working Group meeting, held on February 4, 2026, focused on identifying and addressing persistent challenges with Tutor documentation and its integration within the broader Open edX ecosystem. Participants, including Sarina Canelake, John Swope, and Brian Smith, discussed the "holistic" problem of fragmented and difficult-to-navigate documentation, which often forces users to choose between Tutor-specific docs and the official Open edX documentation. Brian Smith highlighted significant gaps in plugin documentation, while Sarina emphasized that current quick-start guides serve as a "link farm" because the primary Tutor documentation is difficult to update or reorganize. Ahmed Khalid from Arbisoft acknowledged that Tutor docs have suffered from management changes but expressed a commitment to improving them in the coming quarter.
To bridge these gaps, the group proposed several collaborative initiatives, including the creation of a "Tutor FAQ" thread on the community forums and the potential use of short videos from super-users to capture technical knowledge for written documentation. A major point of discussion was the possible reorganization of Tutor docs from a strict a "Diataxis" framework—separating concepts, how-tos, and references—to clearer separate out Operator and Developer docs in a manner that reflects how people browse the docs, to better serve both site operators and developers. Ahmed agreed to discuss internally whether Tutor documentation should eventually be merged into the main docs.openedx.org repository to facilitate easier community maintenance. Action items included Sarina updating the meeting notes, John starting the forum post, and Ahmed advocating for more active participation from Tutor maintainers in community discussions.
Goals
Discuss plans to improve tutor documentation
Identified problem: Setting a Feature via Tutor Plugin. It is documented but there are some items that aren’t clear and some that can help debugging.
Unclear: When I add a plugin if it is an ENV_PATCH or a CORE_SETTING or one of the other Tutor hooks? (More docs on tutor hooks overall seems helpful, I can’t find much )
Debugging: When I add and enable a plugin do I validate that it made it to settings correctly? (You can find it in the env that tutor generates) When I figured that out that helped me a lot, and it wasn’t clear in the docs.
Discussion topics
History: Outside of tutor docs, we’ve spent a few years consolidating docs (educators, learners, developers) onto docs.openedx.org. Tutor docs are separate. The question is, where can we (the docs wg) improve the Tutor docs?
Context: Tutor maintainers have not been super open to upstreaming docs improvements
Context: docs.openedx.org maintainers have created https://docs.openedx.org/en/latest/developers/quickstarts/tutor_quickstart_dev.html and https://docs.openedx.org/en/latest/site_ops/quickstarts/tutor_quickstart_ops.html to work around entry point limitations in Tutor docs
Tutor docs fill two roles: the role that docs.openedx.org fills, plus some of the work READMEs fill, because tutor docs fulfill needs of operators and developers. My issue is around Tutor plugins - there’s some gaps here, if we can’t get things to land in the Tutor docs there are things that would make more sense to land in READMEs than in docs.openedx.org
We’ve had some ideas on how to improve Tutor docs but we feel our efforts have been shot down, see
docs: reorganize sphinx docs for better discoverability by brian-smith-tcril · Pull Request #834 · overhangio/tutor and Onboarding Developer Documentation · Issue #1218 · overhangio/tutor
Common problems we’re seeing
Sarina: Solid entry points for brand new operators & developers
Brian: Documentation around plugins, understanding difference between launch & start, how do I update things, when do I need to relaunch, what are the tutor commands, when should I run them, how do I troubleshoot
I haven’t gotten good results when I search the docs
John: first time administrator perspective, I’ve done a small number of installs, usually for new releases. There are very common things I feel I have to search for every time. For example, enabling new features, installing plugins, enabling discussions (which is a plugin?), enabling themes, enabling the sandbox that allows you to do Python & JS problems that isn’t enabled by default
Ahmed: We’ve been planning to improve Tutor docs in this quarter, issue:
Onboarding Developer Documentation · Issue #1218 · overhangio/tutor - focus on new users how to onboardSarina: How could we help contribute?
Ahmed: Régis, Dawoud moving on to other projects. I’m leading this now, I think we could look more into this side of the project.
John: Ideally we don’t seek divergent docs, but this group has control of docs.openedx.org. Perhaps we start there, eg, “the six steps to get to where native installs used to get to”, and the conversation is less starting-from-nothing but rather, how do we merge them into Tutor docs.
We need a Tutor superuser to help us out here
Sarina: I could make skeletons of what we need to document, but I’m not a superuser so I don’t know how to do (like enabling the JS/Python sandboxes).
Ahmed: This year, we are looking to record more tutorials
John/Sarina: We’re rather against video tutorials as long-term documentation, because it’s difficult to change when things get out of date
Ahmed: we’re looking to come up with documentation on common faqs
Ana: FAQs are good, helps feed into AI
Brian: ChatGPT is pretty good at reading Tutor docs, it’s better that I seem to be able to do, it can look into the Tutor github repo
Ahmed: In my experience, more often than not it hallucinates commands that don’t even exist in Tutor. Feeding the Tutor docs and repo as context seems to be helpful. I see the problem is visibility - if these were reported in a blog post, maybe we could point to FAQs
Sarina: We have tons of tutor posts on the forums already, but Tutor maintainers are not active/helping
John: Need to dig into the Tutor posts - where are people getting stuck?
Brian: A Tutor maintainer going through the forums posts - just recording some audio on how you’d respond could be helpful to those of us writing the docs
Sarina: Who could help us as we ticket up these questions?
Ahmed: You can tag me, I can try to get you answers
Sarina: Diataxis is great for structuring articles, but the user presentation of those docs may need to interleave different types rather than presenting all how-tos then all concepts then all references
Brian: My PR (
docs: reorganize sphinx docs for better discoverability by brian-smith-tcril · Pull Request #834 · overhangio/tutor ) separates out Operators from Developers and links to shared documentation in both places
Action items
docs: reorganize sphinx docs for better discoverability by brian-smith-tcril · Pull Request #834 · overhangio/tutor ?