I think this can now be closed - @choldgraf any objections?

From @agoose77 and my conversation on discord:

We discussed the challenge of knowing what should go into the Jupyter Book docs -- we all share the same concerns about getting the split right.

I've been reflecting on this in the last week, and speaking with you and @rowanc1 has helped clarify things for me.

JB should be tutorial focused (upper diataxis quadrants) over time, MyST-MD moves towards the lower diataxis quadrants extensions/plugins will, over time, be preferentially defined in the "mystmd ecosystem", and enabled as feature-flags in e.g. JB. This means that we can build a coherent spec in one place, and crucially write distribution-like documentation (e.g. JB which ships sphinx proof) that points to the MyST-MD documentation without referring to features that don't exist in MyST-MD land. We will move to a policy of bidirectional cross-links between JB and MyST-MD

At a high level, my vision is that JB the user-facing tool, and mystmd is the power-user tool. This will evolve over time.

I suggest we document the decision somewhere that we can refer back to in the future, then consider this closed. Do you have an intuition for where? Maybe we create some kind of tracking issue for docs improvements in general w JB2, and this language is part of guidelines there?

@choldgraf i think we can probably define this in either MyST's docs, or Jupyter Book, and then embed the figure in both projects.

In meeting: put this in the mystmd docs! (we also talked about putting this in the team-compass, want the information close to the source so that it can be referenced).

As a slight clarification: I think that the mystmd docs should not remove existing tutorials/guides, just that the focus of documentation additions should shift over time towards more detailed guides/explanations/reference materials. Additionally, that shift is only after JBv2 is fully live and discoverable.

mystmd will continue to be stand alone tool, and needs to continue to have stand alone documentation, albeit lighter on the tutorials for books, which we do a better job of in the jupyter-book tool.

That's helpful to understand your thinking @rowanc1 , thanks (I am basing most of my understanding of y'alls thinking based on this comment)

It sounds the short-term plan is still clear: add more how-tos and tutorials to the Jupyter Book docs, and don't add complete reference+explanation material to Jupyter Book and instead use MySTMD for that.

The long-term plan is less clear to me: is Jupyter Book just a subset of the MyST docs? If we add a feature to MySTMD that is relevant to a multi-page site, then would we need to make the same docs addition to both MySTMD and Jupyter Book?

For now, we can just focus on porting over relevant MySTMD docs and not changing anything on the MyST docs side.

If helpful I'm happy to take a meeting to discuss this, but since we have some clarity in the short-term, I'm also happy to just focus on making some docs improvements to Jupyter Book and then seeing how we all feel about this once V2.0 is out

Yeah, I am also not totally sure how things will shake out long term, I think that is ok though. Things will probably get clearer as the tools each get more definition. I think we should take another assessment when JBv2 is out, and until then we should just focus on good tutorials/guides in the JB docs (which is already happening..!).