openedx / openedx/openedx-events
Move and improve event bus public how-to
Open
Nobody has claimed this yet.
event-bus
- Dominant language
- Python
- Stars
- 13
- Forks
- 33
- Avg merge
- 14h 37m
- Merged PRs (30d)
- 4
Description
The Confluence event bus how-to should move to github, and could also be improved (as part of this ticket or a separate ticket).
Implementation details:
- The Confluence doc has a variety of open comments. It would be simplest if these were either resolved and/or ticketed as-needed.
- Recommend first moving the doc as-is to make it simpler to review changes. The initial PR (or possibly commit, but I prefer PR) should just require rST formatting review, but should not require re-reading the entire doc.
- We'll need to decide if event-bus-kafka and event-bus-redis should have separate how-tos in their repos?
- Pro: Engineers don't need to read about a technology that they don't need to deal with.
- Con: Can this be done without making the how-to disjointed between docs, and minimizing duplication? Maybe it is ok to just duplicate.
Other improvements:
- Note: Some of this might be ticketed separately.
- The how-to currently mixes documentation types, and should be split, even if the how-to let's people know where to go to first understand background.
- Can tips from https://github.com/openedx/docs.openedx.org/issues/338 shrink any paragraphs in the document?
- Feedback: "Too much prose. Needs bullets and monospace."
- Are there any code examples that can be copied directly into the doc, rather than (or in addition) to references via links? (This may no longer apply.)
- The broken out Concept doc could do a better job helping someone with the minimum knowledge needed on hooks events to understand why signals are being used for an event bus consumer. (This feedback may be simpler when the signal listener is hidden for producing events.)
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 with the linked Confluence event bus how-to and inspect the openedx-events repository for the appropriate documentation location and formatting conventions. First move the document as-is into rST, then review its open comments and identify improvements or separate tickets; done means the initial PR is limited to the migration and formatting review.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kafka, redis
- Domain
- distributed-systems, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 32/100