OEP-19 app level docs challenges

[robrap]

There are challenges with publishing docs directories that live within an app, as recommended by OEP-19. See openedx/openedx-platform#33327 for details. It would be nice if OEP-19 could provide help for this, which may or may not include updating the recommendation.

[sarina]

@feanil could you weigh in on this?

[feanil]

We've got an experimental version of this now in the edx-platform docs. https://github.com/openedx/edx-platform/blob/master/docs/repository_docs.py

@robrap perhaps you could try and use it or something similar for the event bus docs and based on feedback we can improve/externalize it from edx-platform?

[robrap]

@feanil: Where are those docs in https://docs.openedx.org/projects/edx-platform/en/latest/index.html? Sorry if that should be obvious.

Once we have it working in edx-platform, I think we could simply add a brief note with it as an example to follow. If we want to get more uses first, we could advertise in the Slack documentation channel and see if anyone is willing to try out the pattern. I don't want to be a blocker on this, and I'm excited if we have a solution.

[feanil]

Example here: https://docs.openedx.org/projects/edx-platform/en/latest/references/docs/cms/djangoapps/contentstore/docs/decisions/index.html

[robrap]

Hmm. I'm glad we have something, but its discoverability needs some help. Even when I knew what I was looking for, I didn't find it because I didn't click through the nearly blank pages deep enough to hit the actual content. Also, some of the pages look off, like this one: https://docs.openedx.org/projects/edx-platform/en/latest/references/docs/common/djangoapps/entitlements/docs/decisions/index.html.

I wonder if a cross between what we have now and a more manually created (unless someone scripts this) index page that just lists the app/doc directories for quicker discovery/navigation would be good?

That said, I think the OEP could simply have a note about the challenge around these docs, and a link to this ticket to see possible solutions. This wouldn't force us to prioritize working on this particular issue right now, but would provide some additional direction. Thoughts?

[sarina]

Hi @robrap I'm doing my biannual cleanup of this repo, and revisiting this issue. Has there been any progress in addressing this issue? If not I am open to a note about these challenges in the OEP -- although, I'm not sure where the best place for this note should be so we should talk through that.

[robrap]

I'd say this is more for @feanil (who started a solution), and maybe the Documentation WG? I don't plan on making progress on this, although I am clear on the problem I wish to be solved. 😄