Everyone who has used a traditional notebook seriously has a story about the hidden state problem. You ran cells out of order, you deleted a cell whose variable was still alive in memory, you handed the file to a colleague and it did not reproduce, or you spent an hour debugging something that was not actually in your code any more. The whole community accepted this as the cost of an otherwise excellent tool. marimo starts from the position that this was never necessary, and the documentation does an unusually good job of explaining why.
The reactive execution model is the core idea and the docs teach it properly rather than announcing it. When a cell changes, everything that depends on it re-runs automatically, and the notebook maintains a dependency graph to work out what that means. Your notebook is always in a consistent state because inconsistent states are structurally impossible. The explanation includes the constraints this imposes, and I appreciated that it does not soften them.
You cannot define the same variable in two cells. You cannot rely on execution order. These are real restrictions and the documentation argues for them rather than apologising, which is the right approach because the restrictions are the point. Storing notebooks as plain Python files is the second idea and its practical consequences are larger than they sound.
Diffs become readable. Code review becomes possible. Merge conflicts become resolvable by a human rather than by choosing whose version survives. You can import a notebook as a module or run it as a script.
Anyone who has tried to review a colleague's notebook changes in a pull request and been confronted with a wall of JSON containing base64 image data will understand immediately why this matters. The documentation makes the case with concrete examples rather than assertions. The migration material deserves specific credit. Most tools in this position write documentation for people starting fresh and leave existing users to work it out.
marimo's docs are written with the assumption that you arrive with years of accumulated habits, and they address the specific things you will try to do that will not work, explaining the alternative each time. That is more effort than the easy path and it is the reason people actually complete the switch rather than abandoning it in frustration on day two. The material on turning notebooks into applications is more useful than I expected. A notebook with interactive controls that can be shared as a running app closes a gap that normally requires rewriting everything into a separate framework.
The documentation on the interactive elements is practical and the examples are the kind you can adapt rather than merely admire. The honest difficulties are real. The reactive model will break workflows you rely on. Anyone used to running an expensive cell once and then poking at the results in later cells for an hour has to rethink that pattern, and the documentation explains caching and lazy evaluation as answers but the adjustment period is genuinely uncomfortable.
I would rather the docs said plainly that the first week will be annoying, because it will be, and knowing that in advance helps people push through. The ecosystem gap is the practical cost of choosing the newer thing. Jupyter has had many years of extensions, integrations and institutional support accumulate around it. Something you depend on may simply not exist here yet.
The documentation cannot fix this and does not pretend to, but you should check your specific dependencies before committing a team to a migration. The interactive widget documentation is the area where things move fastest and where I found the occasional gap between what is documented and what is stable. Nothing serious, but it is the part of the project where you should expect to consult release notes rather than assume the docs are settled. This is also not a resource for learning Python.
It assumes you write Python competently and are frustrated by your tooling. Someone earlier in their journey should learn the language first and come back when the notebook problems start to bite, because until you have been burned by hidden state the argument here will not land. Four point four is high and I think it is earned. This is documentation that explains a design philosophy convincingly, respects the reader's existing knowledge, and takes seriously the work of getting people across a genuine behavioural change.
Held back only by ecosystem maturity and the real friction of the transition, neither of which is a documentation failure.