search

jupyter-book / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
206 stars 61 forks source link

⏩ Simplify quickstart guide to use `mamba` #1454

Closed agoose77 closed 2 months ago

agoose77 commented 2 months ago

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

changeset-bot[bot] commented 2 months ago

⚠️ No Changeset found

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.

This PR includes no changesets When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

agoose77 commented 2 months ago

@jnywong would you possibly be happy to take a look at this?

jnywong commented 2 months ago

Happy to! 👍

rowanc1 commented 2 months ago

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.

jnywong commented 2 months ago

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.

agoose77 commented 2 months ago

@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.

choldgraf commented 2 months ago

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.