openedx / openedx/openedx-events

Move and improve event bus public how-to

Open
#238 4 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.