Help us improve the Open edX developer docs!

Development
#1

Good day everyone! We’re looking for your input on improving the Open edX developer documentation.

Your responses to this brief survey will help us greatly. https://forms.gle/T2JS9enCEk5QkJHR9

Responses received by next Tuesday evening will be given the most weight. So if you feel strongly about the developer documentation, please answer promptly.

Thanks!

6 Likes
#2
#3
#4
#5
#6

Thanks! I’m happy to hear about this initiative.

I was a bit surprised that there were no questions about: where people look for documentation, where people expect to find documentation, API documentation in general, documentation format in general, nor how documentation should be maintained.

Personally what I would like to see (in the long term, not necessarily in the next six months) is a focus on systematic reference documentation. i.e. things like: every repository should have a README that clearly explains the “what” and the “why”; every API should have a description and a usage example; every setting and feature flag should have a description; every plugin/integration point should be documented with an example, and so on. Django is an example of a project that does this well.

4 Likes
#7

Thanks to all who contributed their thoughts and experiences on the Open edX Developer documentation and training survey. We have compiled the results and shared them at Developer Documentation and Training Survey Results - 2021-Jan.

#8

@braden I agree that the discovery and standardization of documentation is a big gap in the platform.

Regarding standardization, we have made some recent progress.

  • We have taken strides in providing a standard framework for annotating settings and feature flags, invested in a doc-a-thon to get us started on using it, which now results in reference documentation.

  • We now have a repo-health check that verifies the existence of README files in each of our repos, with some minimal quality checks.

  • We have rolled out conventional commits as a standard to document code changes. My hypothesis with this effort is that it will provide more rigor in our documentation efforts at every code change.

Having said this, I know there is still a lot more to do. I’m looking forward to working with you all to make it happen.

Regarding documentation discovery, I’d like for us to make a few critical decisions on this so we can move forward with a strategy.

1 Like