Closed agoose77 closed 2 months ago
Latest commit: fbd561e1731b414357fb8c8f5f39dcf25a8a15ce
Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.
Click here to learn what changesets are, and how to add one.
Click here if you're a maintainer who wants to add a changeset to this PR
@jnywong would you possibly be happy to take a look at this?
Happy to! 👍
It looks like the tabs for different options have been removed in #1433. Can we bring them back?
https://github.com/jupyter-book/mystmd/pull/1433/files#r1713825789
There is currently no longer any documentation on how to install from pip and npm (actually, they are still in the reference, but they are not linked from the tutorial). The current structure also buries the lead significantly - if you know what you are doing pip install mystmd
works out of the box, and then instructs you on how to install node. If you know npm, it is again one line. Tabs are able to highlight those workflows for people who are not using conda.
This PR came off the back of feedback from a tutorial we just gave. But I like your suggestion @rowanc1 of using the tabbed component for discoverability of other methods.
@rowanc1 a signal that we're picking up increasingly is that you use Python and most likely know about / use conda. In reality, if you are having to use new tools, just using conda is the fastest way to get people started.
Being on PyPI is useful in-and-of itself as a binary story for our compiled code. But there's a lot less to go wrong in "Just use conda".
I think we can better surface the "advanced installation" information that's already partly linked, though. I'll iterate on Jenny's points and think that through next week.
Oops I didn't see this PR get opened, sorry! I actually did some of the same content work over in this PR as well:
happy to remove that and focus on this one though.
@rowanc1 to your question about installing, my reasoning was that we want tutorials to be as simple as humanly possible, and meant to be followed literally from top to bottom. That's based on the principles of tutorials from the Diataxis documentation framework that I've found helpful to keep things simple and focused. We don't have to literally follow that if you think there's a better way of presenting the information.
My feeling is that we want all the options, considerations, etc to be documented on the install page. That way the tutorial stays as simple and actionable as possible. It should be designed for the "most common new user" based on our assumptions about their background. I feel like the conda forge
distribution is the safest bet to start with, but if we get clear signals that people are coming from other backgrounds, we should update the tutorial.
However, as @rowanc1 notes we lost a lot of cross-references to that page. I think we should liberally cross-link that page from the Get Started
tutorial and re-introduce those.
Instead of going into detail about provisioning
node
, let's just go all-in on conda-forge; there's already a detailed article on installing manually