search

openedx / open-edx-proposals

Proposals for Open edX architecture, best practices and processes
http://open-edx-proposals.readthedocs.io/
Other
44 stars 32 forks source link

OEP-19 app level docs challenges #530

Open robrap opened 11 months ago

robrap commented 11 months ago

There are challenges with publishing docs directories that live within an app, as recommended by OEP-19. See https://github.com/openedx/edx-platform/issues/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 commented 4 months ago

@feanil could you weigh in on this?

feanil commented 4 months ago

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 commented 4 months ago

@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 commented 4 months ago

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

robrap commented 4 months ago

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?