old and incomplete docs

[CodeWithEmad]

XBlocks are the heart of Open edX. Yet, somehow the documentation around it is not complete. There are a lot of places that are referenced for future fixes or mentioned TODO. like:

• There's no information about Runtime services. https://docs.openedx.org/projects/xblock/en/latest/runtime.html#xblock.runtime.Runtime.service I found this in Jira but it's quite old: https://openedx.atlassian.net/wiki/spaces/AC/pages/161400730/Open+edX+Runtime+XBlock+API
• https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/introduction.html#other-open-edx-resources

  You, the user community, can help update and revise this documentation project on GitHub.

• Nowhere inside the docs is mentioned about cookiecutter-xblock, but I think that's the standard approach to start with xblocks. https://edx.readthedocs.io/projects/xblock/en/latest/xblock-tutorial/getting_started/
• No reference to needs and wants decorators. (I know we can find the class method description https://edx.readthedocs.io/projects/xblock/en/latest/xblock.html#xblock.core.XBlock.needs but it's not clear for someone who's trying to develop an XBlock)

PS. We can add a tutor approach for installing xblocks as well.

@openedx/axim-engineering

[CodeWithEmad]

Also, the URL in the repository about section return 404 https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/overview/introduction.html -> should be https://docs.openedx.org/projects/xblock/en/latest/index.html

[sarina]

Hi @CodeWithEmad - is this a ticket you're planning to tackle, and would like some advice? Or are you making a general ticket for someone else to work on?

[CodeWithEmad]

Hey @sarina. I am interested in contributing to this project, but I am not fully current with the recent Xblocks changes. It would be very beneficial to have a brief discussion with someone who is more closely involved with Xblock-related matters.

[sarina]

@CodeWithEmad ah sorry that's not me 😅

I think some of it you could get started on like adding notes about the cookiecutter. This seems like a big ticket that would probably benefit from multiple PRs to make smaller changes to get feedback on. You could also try posting specific questions in the forum (maybe one at a time, to generate a more focused discussion)

[kdmccormick]

@CodeWithEmad You are right, the XBlock docs could really use some work, and your suggestions are good ones. +1 to Sarina's suggestion with breaking of proposal into smaller PRs, and the cookiecutter note is definitely a safe place to start.

I'm happy to discuss the recent and upcoming XBlock changes so that you have all the information you need. Is there anything in particular you are wondering?

[CodeWithEmad]

Thanks for your suggestions. I'll create smaller PRs to update the docs but it might take a while. I'm also open to any suggestions.

Well, I'm not the master of writing XBlocks, but for starters, one thing that I didn't find anywhere was the runtime services list and how the "needs" and "wants" decorators work and what the differences are. also, what about the React in xblocks? I find the proposal about the XBlock v2 and the XBlock rending summit, but I've no information about them.

[CodeWithEmad]

as the first attempt to improve the XBlock repo, I made this to clean up the readme and some smaller fixes:

https://github.com/openedx/XBlock/pull/775

Also, the link inside the repos URL returns 404: https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/overview/introduction.html

[sarina]

It's here: https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/index.html

[CodeWithEmad]

Yes @sarina, I'm reading xblock docs from docs.openedx.org I mean here:

[sarina]

@CodeWithEmad thanks for catching that, I've fixed it.