The blended project [BD-34] Developer Docs Framework needed to end early due to resourcing constraints. This page captures status from that project, as well as additional developer documentation related notes.
The following BD-34 work was either reverted or closed until we can come back to this.
According to OEP-19 on Developer Documentation, we had decided to consolidate Open edX platform scoped developer documentation in https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/. However, the repo was given little attention, so BD-34 attempted to update the outline.
https://github.com/edx/edx-developer-docs/pull/45
Revert contains updated outline, which includes a bunch of stubbed pages.
Reverting revert would require us to reverse the redirect documented here.
Open feedback
Outline would need clarification of what belongs in "Start" vs "For all devs".
See “Fix Sphinx theme” below, since the updated outline uses level 3 (or 4) in sidebar.
There was an attempt to remove the Legacy Developer's Guide from https://github.com/edx/edx-documentation/, by updating it and moving it to the supported Developer Documentation in https://github.com/edx/edx-developer-docs.
Note: All legacy doc PRs have been closed until this work starts up again. Also, they all were written on top of the “Updated Outline” above, before it was reverted.
Legacy Doc PRs (closed):
Other work before removing the legacy Developer’s Guide
See Legacy docs and new outline (Google Doc) for additional planning notes.
Custom 404.html from legacy docs which points to newer Developer Documentation.
Individual redirects for popular legacy docs directly to moved version of docs.
Resolve unanswered question about Glossary
Used to be a shared document inside edx-documentation.
Nimisha wrote: I now know exactly what I’d like to see as the deep-dive on the arch-related docs that I believe we need. Please see https://sarahtaraporewalla.com/agile/design/architecture/Defining-a-Tech-Strategy. We have most of the information that Sarah lists here, but in disjoint places and not with associated “words”.
Draft architecture PRs (closed):
Publishing code repo docs to Readthedocs
May need to update Publish Documentation on Read the Docs
If readthedocs admin page becomes unmanageable, will need tooling using API like Ned’s spreadsheet of readthedocs projects from a Hackathon.
How should an owner decide when this is warranted? Is it always warranted?
We don’t have a documented best practice for links that work from inside github and readthedocs.
Possible solution: https://github.com/readthedocs/readthedocs.org/issues/2926
The cookiecutter does not have a great default readthedocs outline.
See edx-toggles and edx-django-utils for possible enhancements.
Related: We don’t have a best practice for including docs from inside the repo in the main published docs.
See edx-django-utils docs/monitoring/README.rst for a temporary solution and pointers to other solutions.
Fix Sphinx theme
UPDATE: See https://github.com/openedx/edx-sphinx-theme/issues/184
https://github.com/edx/edx-sphinx-theme has several issues:
Many styling issues for header levels in sidebar (indent, size, twisty, selection)
Worse for levels 3 and 4
Menu is broken on mobile.
Styles are easy to break. See (temporary) docutils constraint due to styling issue.
UPDATE: This constraint was removed.
Potential solutions:
Switch to using a maintained Sphinx theme.
A logo can be configured, if that was a past sticking point.
Updating edx-sphinx-theme with clear instructions of what theme it is based on and how to keep it in sync with updates, and what features are custom to this theme.
Ownership and resourcing?
open-edx-proposals maintenance
make requirements doesn’t work until after you have sphinx installed.
make develop complains about a missing directory. Should this even be used?
Should the Sphinx Makefile be separated from the main Makefile, like in edx-developer-docs? Or, does someone know how to make this work?
Developer Documentation and Training Survey Results - 2021-Jan
BD-34 Dev Docs Stand-up Notes (Google Doc)
Includes many useful notes and background for any future effort.
Learned a lot about what might be needed going forward.
Developer Documentation and Training Survey Results - 2021-Jan had interested results.
Made progress on some technical issues in the edx-developer-docs repo.
This work takes heavier engineering support than planned for.
Sphinx related work, readthedocs theme, readthdocs admin, redirects, sphinx config, etc.
Open edX experience to help catalog, create backlog of work, review updates, and generally guide the documentation creation or maintenance process.
It would be helpful if the technical writer either had Open edX experience, or was going to be a longer term resource.
This project probably needs more resources than one technical writer and one part-time engineer was not enough.
I wish we had gotten UX input lined up earlier in the process.
How could we have avoided rolling back work?
Tried to be iterative, but outline was added with links to stubbed files. Stubs were helpful in understanding direction, but should have been cleaned up before merge.
Trying to cull and update legacy docs draws out the timeline where we have docs in two books and two repositories. Ultimately, we never completed this.
I’d prefer moving legacy docs as-is to new repo. Either to a legacy doc directory, or with minor adjustments to account for the new outline. Then, improving or deleting docs as-needed. The downside is that the new repo also contains out-of-date docs until updates have been completed. The upside is that if other priorities take over, we have the win of fewer locations for developer documentation.
Felt like outcomes of the project was a moving target at times. I thought there was agreement on consolidating legacy docs, and then later it felt like the value of this effort was being questioned.
[idea] Maybe a personal or non-edX readthedocs account could help for creating draft docs on readthedocs for PRs?
Discovery of documentation is still a large open question.
Will improving and consolidating to edx-developer-docs help?