openedx / openedx/openedx-platform
Improve documentation use of common and openedx directories
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8.2k
- Forks
- 4.4k
- Avg merge
- 6d 18h
- Merged PRs (30d)
- 42
Description
When someone new to the platform (or not new to the platform) is trying to determine where a new app should be created, it is not very clear. This is made more complex due to the lack of clarity around usage of the common and openedx directories.
Documentation Notes/Questions:
- Update READMEs to clarify when to use and when not to use each directory.
- Ensure docs can answer the question: Where should I create my new app?
- Potentially create an ADR for any decisions that need to be made.
- Ensure docs are cross-referenced appropriately so the appropriate location can be found.
Usage Questions:
- Are there differences between common and openedx that are important?
- One reason openedx was created was to enable a "feature" to contain all of its templates, etc., in the same directory with its supporting code.
- Is this something that is not available under "lms" and "cms"?
- Is this something that no longer matters as we are shifting to MFEs?
- Do we need/want both, or are we just stuck with both?
- Was it simply a mistake to have lms and cms specific apps in openedx? Should it only include features common to both?
Other notes:
- This is related to guidance around when and if someone even needs a new app, or whether or not to use an existing one.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the existing README guidance for the common, openedx, lms, and cms directories, then review any existing app-placement guidance and ADRs. Done means the documentation explains where to create a new app, clarifies when each directory should or should not be used, and adds appropriate cross-references; record unresolved architectural decisions in an ADR if needed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100