overhangio
Onboarding Developer Documentation
Is your feature request related to a problem? Please describe. I am working to onboard 10 engineers (myself included) to the Open edX platform and each individual has struggled through the tutor documentation for development. Particularly, the initial getting started documentation seem to have opportunity for consolidation and/or refactoring.
Describe the solution you'd like Here are the two pages that I see the best opportunity for consolidation:
- https://docs.tutor.edly.io/dev.html#open-edx-development
- https://docs.tutor.edly.io/tutorials/edx-platform.html#working-on-edx-platform-as-a-developer There are important explanations in each of these pages but there are a few inconsistencies that I think could be cleared up. For instance:
- The "tutorials" page explains step-by-step how to reference your local workspace, while the "first-time" page assumes you have it already forked.
- The "tutorials" page explains what "tutor mounts add ..." does while the "first-time" page explains what "tutor dev launch" does.
- Both documentation references "tutor local" halfway through the page but neither links to or explains what the difference between "tutor local" and "tutor dev".
- Lastly, I think the "first-time" document should reference the "tutorials" link _at the end of the documentation and so it flows into that page as next steps, rather than two docs that start off similarly.
I also believe it would be better to include this page about installing tutor main, as a sub-page or section to the installing tutor documentation:
- (Tutor main): http://docs.tutor.edly.io/tutorials/main.html#installing-tutor-main
- (Tutor install): https://docs.tutor.edly.io/install.html#installing-tutor The reason being was by the time I found out what tutor main was in the tutorial I was confused as to why I would want to be developer contributing to open edx and not working on the master branch.
Describe alternatives you've considered Alternatively, there could be a clearer navigation menu that would include ability to see more sub-pages at once rather than just the one selected. I had hard time realizing when I was moving into a new section when I clicked on different links throughout. Or there could be a one-stop-shop menu for all engineering / developer related content for contributing to the platform.
Additional context I have now been able to run a release branch of the platform locally and make changes. However, I still had questions about what really was tutor doing. I found this video extremely helpful in solidifying my understanding of not just what tutor is, but why it came about: https://www.youtube.com/watch?v=BzNcrmyFpw4. I would recommend having this video embedded in one of the first pages on the tutor documentation.
Thank you for reading through all of this! I hope this was found as helpful, and not just a complaint list. I was tempted to make a pull request but with the amount of refactoring involved I figured this was the best format to make suggestions to someone who has a better understanding of the tool.
@tonybusa I appreciate your close reading of the docs and this proposal. I'm hopeful @regisb or the tutor maintainers team can give some feedback, and then you can make a PR with the agreed-upon changes.
Likewise, I appreciate the thorough explanations. We acknowledge that Tutor docs need to be reorganized. This effort had started in #834, but stalled because of implementation disagreements. It turns out that rewriting docs is harder than refactoring code. Right now, the team is gearing up for the Teak release, and rewriting docs would create a ton of conflicts, so maybe this will have to wait until after the release (June 2025). But we will most definitely work on this issue.
Thanks for reporting this and adding an in-depth context. As Regis mentioned above, there is some preparation work going on for Teak release. While that work does not block document changes, the conflicts will be tricky to manage. Tutor has evolved from using for Open edX deployments to used for both deployment and development. The documentation at this point somewhat reflect that, where the index page emphasizes on quick installation aspect of Tutor. The organization of the content can be better since there is always a room for improvement.
