[alexisread]

I built this sort of notebook before, the issue I have with notebooks though is version control, debugging, testing, and general integration eg. with deployment processes.

In a large org, if you're missing any of them it's a showstopper, so lowest common denominator applies ie. basic comments.

Ideally, the language would allow for scoped markdown+ comments, and be able to build a document from linking params and functions, into a narrative (Obv. this requires you do your project overviews in the correct location, but that's a small issue).

I suspect LLMs will be able to help document code shortly.

[hugetim]

The package Jeremy Howard uses for Claudette, nbdev, actually does address the notebook pain points of version control, testing, integration, and deployment: https://nbdev.fast.ai/ (Debugging is already a strong point of developing within a notebook.) But it's admittedly used mostly for solo projects or small teams and may not be ready for large orgs.