Open choldgraf opened 4 months ago
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!
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:
So we'll consider this one done! Leaving it open just to keep this more visible
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:
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
cc in particular @rowanc1 and @agoose77 , I want to make sure that us three at least are on the same page here!