Developer Docs Framework Notes

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.

In-Progress PRs (Reverted/Closed)

The following BD-34 work was either reverted or closed until we can come back to this.

Updated Outline (Reverted)

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.

• Revert "[BD-34] New dev docs outline and user interface (#35)" by robrap · Pull Request #45 · openedx-unsupported/edx-developer-docs

  • Revert contains updated outline, which includes a bunch of stubbed pages.

  • Reverting revert would require us to reverse the redirect documented here.

  • Open feedback

    • Feedback from Adam Butterworth (Google Doc)

    • 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.

Retire Legacy Developer Docs (Unmerged/Closed)

There was an attempt to remove the Legacy Developer's Guide from GitHub - openedx/edx-documentation, by updating it and moving it to the supported Developer Documentation in GitHub - openedx-unsupported/edx-developer-docs: Words that developers want to read.

• 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):

  • [BD-34] PR for dev documentation related to security considerations (like preventing XSS) by PrecisionWordcraft · Pull Request #36 · openedx-unsupported/edx-developer-docs

  • [BD-34] PR for dev documentation related to extending the Open edX platform by PrecisionWordcraft · Pull Request #37 · openedx-unsupported/edx-developer-docs

  • [BD-34] Move legacy docs Section 1 info into proper slots in new repo by PrecisionWordcraft · Pull Request #41 · openedx-unsupported/edx-developer-docs

  • [BD-34] Reduce number of bullets on contributing/index.rst to remove refs to obsolete or future content by PrecisionWordcraft · Pull Request #42 · openedx-unsupported/edx-developer-docs

  • TODO: Close PRs with pointer to this doc.

• 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.

Architecture Related Docs

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):

  • [BD-34] WIP: Precision wordcraft/architecture docs sample by PrecisionWordcraft · Pull Request #43 · openedx-unsupported/edx-developer-docs

Other Developer Documentation Notes

Publishing code repo docs to Readthedocs

• May need to update Publish Documentation on Read the Docsarchived

• 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?

Repo 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?

Other resources

• Google Analytics data for Readthedocs traffic

• https://openedx.atlassian.net/wiki/spaces/AC/pages/2445476472

• https://openedx.atlassian.net/wiki/spaces/AC/pages/2554331530

• BD-34 Dev Docs Stand-up Notes (Google Doc)

  • Includes many useful notes and background for any future effort.

BD-34 Retro Notes

• Learned a lot about what might be needed going forward.

• https://openedx.atlassian.net/wiki/spaces/AC/pages/2445476472 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?