[blog] Rationale for splitting into two projects

[choldgraf]

We've had a few questions from folks who are implicitly or explicitly asking for a rationale for why Jupyter Book split into two projects. We've touched on this topic in a few posts, but never as a dedicated conversation and never to significant depth.

• https://blog.jupyterbook.org/posts/2024-11-15-jupyter-book-2-alpha
• https://executablebooks.org/en/latest/blog/2024-05-20-jupyter-book-myst/
• https://executablebooks.org/en/latest/blog/2023/new-project-members/

Suggestion: Dedicate a blog post to the reasons for separating the two projects

I think it could be a helpful record of history, and action of transparency, to describe the rationale behind splitting the sphinx and JS-based stacks into separate efforts. This shouldn't be a matter of "blaming" one stack or the other, and it should stick to facts. At the end, the reader should be able to understand why we made these decisions, and our thinking for the pros/cons about them.

What major points come to mind?

Here is a brainstorm of some of the main ideas that came to mind when I first thought this through. I'd love any suggested additions, edits, etc.

• Big picture
  • We can serve the entire research communication lifecycle with one ecosystem now
  • We'd have to build so much complexity on top of Sphinx that it would be easier to build it natively.
• Docutils complexity
  • Docutils is a powerful tool, but was built 12 years ago and has a lot of complexity that is hard to work with.
  • Sphinx has multiple layers of open source communities underneath it, which was hard to navigate (docutils + sphinx, docutils on sourceforge)
• Technical purpose of Docutils is not web-native communication and publishing
  • Docutils doesn't make it easy to separate the "build a document" from the "render it to an output" phase.
  • Outputs are not natively made for the web, nor machine readable for re-consumption.
• Document structure is a strategic asset to control
  • For a project designed around publishing workflows, the document structure is critical.
  • MyST is more valuable as a document structure than a markdown flavor. This lets many flavors of syntax be parsed into the same structure.
  • Partnerships with adjacent communities like publishing will be easier if we can control the document format and output.-
• TypeScript and Jupyter's stack
  • Building in TypeScript allows us to integrate more with interactive computing tools like Jupyter.
  • Typescript and Docutils are very different stacks, and maintaining them both with one team is unrealistic.
  • The decisions around community, maintenance, direction, etc will be better made with two teams than one.
  • TS aligns more naturally with the Jupyter ecosystem.