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.

• 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

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

  • https://github.com/edx/edx-developer-docs/pull/36

  • https://github.com/edx/edx-developer-docs/pull/37

  • https://github.com/edx/edx-developer-docs/pull/41

  • https://github.com/edx/edx-developer-docs/pull/42

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

  • https://github.com/edx/edx-developer-docs/pull/43

Other Developer Documentation Notes

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

Other resources

• Google Analytics data for Readthedocs traffic

• Developer Documentation and Training Survey Results - 2021-Jan

• Toggles and Settings Documentation

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

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