Principles to guide the Jupyter Book transition from Sphinx to MyST

[choldgraf]

As part of our goal to experiment with a MyST backend to Jupyter Book, we'll need to make trade-off decisions about design and development priorities. This is an issue to define a few principles that can help us make decisions in an efficient way. The goal of the issue is both to clarify and align one another on our priorities, and provide guidance that helps us make decisions autonomously.

Here's a brief list of principles to start with, please provide any feedback and make direct edits if you'd like to see something different here!

Design for the best MyST experience, without anchoring on Jupyter Book's v1 implementation

When we're deciding on configuration structure and UX design, we should make choices that provide the best UX for users, rather than choices that try to ease the burden on transitioning from Jupyter Book v1 to v2. This should be our primary guiding principle. It's OK if Jupyter Book v2 users have to do things a bit differently, as long as the UX and functionality are better.

Jupyter Book should be as lightweight as possible

We want Jupyter Book to be as lightweight as humanly possible. This might even mean that it is just a light pre-configured MyST distribution. That's OK, there's still considerable value in the brand of Jupyter Book, and we can decide on a long-term transition to MyST if that's the best path forward.

Jupyter Book should deviate as little as possible from "The MyST way of doing things". Avoid JB-specific configuration options and code that abstracts away MyST. We do a lot of this with Sphinx, but that's because Sphinx has drawbacks we need to design around. If we identify things that need to be different in MyST, strongly prefer improving it in MyST rather than implementing anything Jupyter Book specific.

One way trip from Jupyter Book v1 to v2

It's safe to assume that users will use either Jupyter Book v1 (with Sphinx), or Jupyter Book v2 (with MyST), they will not switch back and forth between them. We should prioritize one-directional transitions from v1->v2 unless there's a very low-maintenance way to maintain v1 workflows as well.

It's OK to feature-freeze Jupyter Book v1 now. It's OK to consider Jupyter Book not-actively-maintained after NN months (which we can decide based on MyST uptake and functionality).

How to decide on transition pain vs. maintenance burden

For transitioning from v1 to v2, we should prioritize pain to users over increasing our maintenance burden. Focus on building the best end-user experience in order to "make it worth it", rather than de-risking the energy needed to transition in the first place.

We have roughly 4 ways of helping users transition, in descending order of preference:

1. Document how to transition to new workflows (e.g. new config, syntax, etc) and expect users to do it themselves.
2. Provide technology that facilitates transitioning from old to new (e.g. a CLI that auto-generates a new-style TOC from a v1 TOC).
3. Support old config/behavior temporarily, with a deprecation warning and a link to instructions to update.
4. Support old config/behavior long-term with v2.

Generally speaking, the things further down on this list should only be chosen if functionality is either critical to the user experience or relatively easy to implement and maintain.

Feedback

• Is there anything important missing from the list above?
• Does anybody object to the principles described above?

cc in particular @rowanc1 and @agoose77 , I want to make sure that us three at least are on the same page here!

[rowanc1]

Agree on all of this, and good to see it written down! I don't think I have anything specific to add at this point, but will give it some more thought!

[choldgraf]

We agreed in Discord to just leave this as-is, and refer to it in our initiative that's focusing on building out a Jupyter Book MVP:

• Minimum Viable Product of Jupyter Book functionality with MyST #1106

So we'll consider this one done! Leaving it open just to keep this more visible