Move and improve event bus public how-to

[robrap]

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 Doc for writing brief and useful docs docs.openedx.org#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.)

[robrap]

@navinkarkera @bmtcril: Not sure if you still have appetite for any of this work, but I finally created a ticket for this. This ticket could easily be broken into parts if need be.

[bmtcril]

@robrap I probably won't be able to take this on any time soon, and our contract with Navin / OpenCraft is wrapping up once the events-as-config work is done. However as a newly minted core contributor he could pick it up if OC thinks it's a good use of his hours. 😄

[robrap]

Thanks @bmtcril. Good to know that project is coming to a close. I've got a number of potential onboarding improvement tickets, if and when anyone working with the event bus wants to help make some advancements.

[mariajgrimaldi]

@robrap: I'll be working on a docs FC project which aims to include event bus docs from confluence into the repo as one of its features: https://docs.google.com/document/d/1_kU-Rp0KS8XDNNeQnVAjAz4Cqpc_665XMVQ6BuCeNio/edit?tab=t.0#heading=h.1hnlfb82j24c

I'm not sure how much I could take on from this issue, but I'll make sure to review it before moving forward.