Proposed reorganization for learn.scientific-python.org

[drammock]

The homepage (https://learn.scientific-python.org/) is currently just 4 glorified buttons. For now I think we should keep that structure (though reduced to 3, see below). In the following list, the top-level bullets give the proposed title and description for each "button", and sub-bullets explain what content it will link out to.

• Lectures: In-depth narrative Jupyter notebooks that teach fundamental concepts for some of the ecosystem's core packages (NumPy, SciPy, matplotlib, scikit-learn, and scikit-image).
  • content is https://lectures.scientific-python.org, unchanged for now (though we all know the lectures need some refreshing/restyling)
• Development Guide for Research Code: A collection of "good enough" practices for writing and managing research code, so that it is reusable by colleagues (or your future self).
  • content will be the "tutorials" of the current "development guide". Could maybe use a refresh, but is in good enough shape to stand unchanged for now. Landing page will be https://learn.scientific-python.org/development/tutorials/.
• Maintainer Onboarding and Reference Materials: Tools and best practices for maintainers of scientific software projects.
  • Landing page will be https://learn.scientific-python.org/development/guides/. Landing page will (continue to) link out to cookiecutter & repo-review.
  • Bulk of the content will be the current "topical guides", with (over time) addition of the following new content --- perhaps on new pages, perhaps augmenting existing pages (this list is open for discussion):
    • tracebacks, stack levels, debuggers
    • CIs: logs, artifacts, caches
    • CIs: coverage strategies (OSes, dependency versions, nightlies)
    • testing: terminology (unit, smoke, integration)
    • testing: more on fixtures (esp. scope) and marks
    • testing: common flags (-k, --pdb, --lf, ...)
    • testing: helpers for downstream libs (np.testing, pd.testing, etc)
    • dependencies: spec0, lockfiles, when (not) to pin
    • packaging: pypi vs conda-forge, grayskull, trusted publisher action
    • git: rebasing, squashing, cherry-picking, merge conflicts, force-pushes, bisect
    • docs/websites: overview of the landscape (docutils, sphinx, myst, rST, markdown, themes, sphinx_gallery, nbsphinx, jupytext, mkdocs, hugo, etc)
    • accessibility: "accessible docs" page and "accessible notebooks" page
    • translations: overview of landscape and tooling
    • code review: possibly just a page with short, big-picture guidance and a link out to https://intersect-training.org/Code-Review/best-practices.html
  • Additional content: the current developer guide "principles" and "patterns" sections should (IMO) get incorporated into the topical guides. They're relevant to the same audience, and not different enough in form to justify living in a different section of their own.
• Documentation Guide goes away (incorporated into onboarding section, above).
• Contributor Guide goes away. Still TBD if/where the content will migrate to.

Below the 3 main "buttons" I think it makes sense to add a short paragraph about what resources we aren't trying to provide / what use cases we aren't trying to serve. For example:

These resources are aimed at scientists writing their own software (in Python), and maintainers of large scientific software packages. If you're new to Python, see these resources (official py tutorial, software carpentry). If you've done some Python coding before and are wondering how to get involved with a Scientific Python project: the process can vary, so check the project's website or repository to see if they have a Q&A forum, community calls, office hours, or other mechanism for welcoming new contributors.

Feedback/comments welcome on all aspects of this proposal. This will probably end up being a series of PRs rather than one big move; once the plan has stabilized I'll propose a sequence of steps.

[stefanv]

We have a pretty good separation between Scientific Python and PyOpenSci concerns, so we should consider whether "Development Guide for Research Code" isn't better served by them ¹.

In terms of topics, the more relevant it is for library maintainers and authors, the better. I'd consider "git: rebasing, squashing, cherry-picking, merge conflicts, force-pushes, bisect" too generic, and better referenced externally (e.g., but not limited to, ²).

It'd also be good to get @henryiii's input here, to see how he'd feel about such a restructuring, or whether he has alternative suggestions.

Footnotes

1. https://www.pyopensci.org/python-package-guide/
   https://www.pyopensci.org/learn.html ↩

2. https://www.atlassian.com/git/tutorials ↩

[KirstieJane]

I really like the idea of reducing duplication with other projects / communities / resources across the ecosystem.

In addition to the 3 proposed "buttons" I wonder if there's a footer or some logos to explicitly direct visitors to the page to other endorsed resources? PyOpenSci has been mentioned and that seems a really clear one. There could be others that Scientific Python want to include too?

The point is just ever so slightly pivoting the message from "these resources are for maintainers" to "our resources are for maintainers and look at all these other ways you can learn to contribute to / use scientific Python packages" 🌱 🌳🕸️

[henryiii]

More is not always better. Having a focused guide that covers the most important things that someone can reasonably read in is better than a giant guide that is too much to read, and quickly becomes unmaintained because it covers too much. So whatever we do, I think we need to strongly prioritize quality over quantity. I think clearly keeping sections for different purposes is helpful, too.

Most of the new pages listed are not aligned with the current guide, which is opinionated and doesn't devolve into long discussions about different tools. We select one tool in most cases, and just cover that. Multiple backends and licenses are "selectable"/covered, because there's isn't a "one size fits all" choice. I think documentation is so evenly divided that mkdocs and/or mystmd could become tabs/pages. But I'd not cover random unrelated stuff like Hugo, etc. I don't think I'd add discussions to the current guide, either; it's focused on specific recommendations for tools and how to use/configure them. Of the topics above, the ones that look useful are:

• Expanding the testing page with things like marks; currently it's just two sentences
• Expanding the CI page, there's a common needs section already that could include things like nightlies and testing minimum dependencies

(I'd also add that I've always wanted to move the site to Hugo and match the styling with learn, but don't have time to do it by myself)

Also, we already cover things like flags, we supported Trusted Publishing within 24 hours of its release (I added it from PyCon immediately after it was announced), etc. Have you read the pages as is? Or were they too long to read already? :D

Seriously, though, I'd not propose writing a bunch of stuff without reading what's been written carefully. I'd also look at how it's all merged together into one tight system in a single repo. We did a lot of work in the first Scientific Python Developer Summit to get it all together and interlinked.

We currently have the guide in several sections: the "topical guides", which is the most important thing (to me), and is tightly synced with the cookie and sp-repo-review. That's what I'm mostly talking about above. That needs to stay separate, and must live in the cookie repo, since it's in sync with other parts. Some pages literally are rendered from the cookie, actually. The badges cross-link.

The other sections are "tutorials", "principles", and "patterns", all of which could be expanded, or possibly moved around per above. Quite a bit of the above is more relevant there. It's targeted at the same audience, but it's not the same Diataxis section: the guide is a guide, meaning you follow it, it's a set of recommendations. It's not a discussion of what "testing" is, etc. I think some of the more philosophical topics above would work well in "principles", in fact, one of them is exactly what @lundybernard is working on in scientific-python/cookie#619. More of those, like a page on tracebacks and debuggers, would be good, I think. This is a good place to discuss pinning, why you shouldn't use lock files¹, etc.

Git is a tricky one; it's a big topic and it's not really related to Python; I'd rather point at the multitude of good material out there. If we added a page, it would need to be optioned, and all our options are likely quite different. Mine is right, of course. :P

Footnotes

1. Remember the target audience: this is library developers, not analysts, for example! Also, now that you can set an upper date when resolving with uv and pixi, I'm not sure lock files are useful anymore except for specific security applications. Though both tools still tend to force them on you currently, and that causes negative side effects, like resolving older versions of packages because it's trying to make a single solve for a range of Pythons. ↩

[henryiii]

The "topical guides" is the upper right quadrant; and since we don't have a "reference" section, it's a bit of that too. I constantly copy-paste stuff from the guide page on Style and CI, actually. The "principles" section is the lower left (explanation). The "tutorials" section is the upper left. It's quite intentional that it's split up this way, and not all merged into one.

[henryiii]

In addition to the 3 proposed "buttons" I wonder if there's a footer or some logos to explicitly direct visitors to the page to other endorsed resources? PyOpenSci has been mentioned and that seems a really clear one. There could be others that Scientific Python want to include too?

The home page already has a section "Related Resources". PyOpenSci is linked, along with three other resources.

[stefanv]

Thanks, Henry. I was reading the guide today and noticed that there is only a table of contents, and not a "section navigation" on the right—I thought that would have been useful, especially with some of the longer documents.

FWIW, we are likely going to move away from Hugo and more towards mystmd—I'm happy to discuss why, but in short it makes sense from a community alignment / de-duplication perspective. I also think this material would be easier to port to mystmd than Hugo, given the rich set of components/directives they already provide. (If you are interested in seeing that happen, I'm happy to get it going.)

[henryiii]

Maybe it's good I'm slow, then. :) I was just thinking Hugo submodules would be a good fit, but hopefully we can solve it with mystmd. I'd be fine with a mystmd conversion! I assume learn would move first, then we'd try to integrate with that in the guide.

I've never really liked the fold-down ToC (I like the integrated right sidebar contents better), and a search would be nice too - probably good things to ensure are there after a mystmd conversion. I think the side bar is easy in mystmd? At least I know it's there in JupyterBooks.

[stefanv]

I'm glad to hear the optimistic response!

Folks can get a rough sense of what mystmd docs looks like here: https://mystmd.org/guide

@matthew-brett and @pxr867 are working on porting the Lecture Notes, based on some work @melissawm did at the first Summit (pre-mystmd engine, but with JBv1 already using myst syntax).

[drammock]

In addition to the 3 proposed "buttons" I wonder if there's a footer or some logos to explicitly direct visitors to the page to other endorsed resources?

@KirstieJane this sounds like what I was trying to do when I said in the issue description:

Below the 3 main "buttons" I think it makes sense to add a short paragraph about what resources we aren't trying to provide / what use cases we aren't trying to serve. For example...

did you miss that, or am I misunderstanding your suggestion?

[drammock]

@henryiii thanks for your perspective, it's helpful to know about your motivations for including/not including topics. Thanks also for reminding me about the tight integration between the topical guides and the cookie, I'd forgotten about that and it may influence what course of action will make sense here.

One bit of background info that I should have included in the PR description: we had a long discussion about the "learn" content at the summit in May (that you weren't able to attend). The upshot of that discussion was, in a nutshell: we (maintainers of Scientific Python packages) should only provide content that (1) is not available elsewhere, and (2) makes our work easier. The rough (though not unanimous) consensus was that:

1. the lecture notes should stay (nothing comparable exists elsewhere)
2. the material oriented toward first-time contributors should go (doesn't make our work easier; some comparable stuff exists elsewhere)
3. the reference/recipe info in the topical guides should stay (useful to maintainers)
4. the "tutorials" should stay, not because we consume them, but because it saves us from having to frequently explain/teach that material to scientist colleagues who lack experience in packaging/maintaining code that others may use. (sidenote: IIRC @danielballan expressed a strong preference for that material to stay put, so @stefanv's suggestion to move it into PyOpenSci may meet some resistance)
5. A missing category is "onboarding" resources to help get new maintainers up to speed more quickly. That is the purpose of the proposed additions. For domain packages, we often can't assume a CS background for folks interested/motivated to do maintainer work, which motivates the suggested inclusion of some topics.

---

I didn't recognize the existing structure as a reflection of the Diátaxis framework, in part because when I've applied the framework to projects, I've always thought of each quadrant as a different view onto the same content. In other words, I'm used to (ideally) having an API reference page for foo(), a how-to recipe for performing a common analysis goal with foo(), a tutorial demonstrating all the optional params of foo() for handling edge cases, and a discussion page describing the pros and cons of foo() versus qux() (and/or the pros and cons of foo(method="bar") vs foo(method="baz")). Here, it seems like many topics are present only in one or two quadrants (in particular, the content in "principles" and "patterns" doesn't seem to overlap at all with the topics found in "tutorials" or "guides"). I don't think that's necessarily a problem: if we're documenting "scientific software development and maintenance" there will be some topics that don't really need a pros-and-cons discussion (e.g. enforcing style: everyone should use a checker, nearly everyone uses ruff or black, they do very similar things; there's just not much to discuss there). Likewise some onboarding topics don't have a single best practice or most common tool that can be recommended/endorsed, so they won't have a how-to recipe.

Given that we are both on board with the Diátaxis approach of separating content for different purposes into different pages, I think it's worth (re)considering whether it's also necessary to keep them in different sections (as you've suggested). Maybe that will turn out to yield the best result, but it's not actually a requirement of the Diátaxis framework (discussed on this page, in particular the user-first thinking section). As stated there, I think it comes down to the user: experienced maintainers will want to find their copy-pasteable recipes quickly, which might be easier if all recipes are in one place. On the other hand, for onboarding new folks, a linear read-through where pages about one topic (e.g. testing) are clustered together might offer a better learning experience than a structure where the linear read-through is "all the tutorials, then all the recipes, then all the discussions". To give one example of how intermingled content types could work: if each page is clearly signposted (e.g., "choosing a pinning strategy" signals "I'm a discussion" whereas "how to pin a dependency" screams "I'm a recipe") then having the two pages adjacent in the same section probably won't confuse readers (or authors) as to each page's purpose. It would be good if we could find a way to provide a view on this content that makes things easy (enough) for both types of user.

That said, perhaps the tight integration with the cookie forces our hand in keeping the existing topic guides segregated from everything else? I'm inclined to defer to you in answering that question, but would like to know approximately how hard would it be to intermingle pages that are and are not linked to the cookie in the same section.

---

Two other small comments:

• points 4 and 5 from the "rough consensus" above lead me to disagree with your statement to "Remember the target audience: this is library developers, not analysts, for example!" Maybe that's true of the topical guides, but not for the whole "learn" site. And as the foregoing paragraphs indicate, I wasn't thinking about the sections as necessarily separate from each other.
• regarding a git tutorial: I fully agree that linking to other resources is preferable. But I still see value in making a page that says "here are some more advanced things you might need to do in the course of your work as a maintainer (merge conflict, cherry-pick, etc). Here's a 1-2 sentence description of each and when you might encounter it, and here's a link to a good (external) resource or two on how to do it"

[bsipocz]

My super off the cuff comment is that I really don't like the branding "Learn" when the material is more in the flavour of reference guide targeting maintainers or those on a track of being maintainers. Learn is great for the lecture notes but not for the dev guide we already have there.

And I agree with Stefan that we very likely don't want to aim it for "Research code" but for libraries. It can still be small, research-y libraries but even then I think there is a clear distinction between the target audiences with pyopensci and SP.

[KirstieJane]

Re: #260 (comment)

@drammock - it's so close to what I was suggesting! It's actually a little hard for me to articulate the difference 😅

I'll try v briefly but if you think they still look the same then let's assume we're on the same page 😁

For more traditional (not open source) collaborations there would be some paperwork associated with using one organization's logo on another's page. It would be formalised as a partnership of some sort. The appearance of the logo means something - an endorsement of mutual value, for example.

Sometimes I think open source projects miss the opportunity to explicitly highlight their collaborations - the message can get lost inside "everyone can participate".

So I think what I'm proposing is just slightly different from "go somewhere else to get this knowledge" and closer to "we endorse these materials because we work closely with these communities".

Reading this back, maybe I'm literally just suggesting adding in the logos 😅 I think we might be saying the same thing!

Thank you for all this design work @drammock! It's so valuable to so many 🙏

[drammock]

One more note regarding @stefanv's comment:

We have a pretty good separation between Scientific Python and PyOpenSci concerns, so we should consider whether "Development Guide for Research Code" isn't better served by them

I included this section because I thought (based on what @danielballan told me) that this is primarily how the current "tutorials" part of the development guide is used --- coaching junior scientists how to write code that, when they rotate off the team, is in a usable and maintainable state for their former team members. I'm not proposing to add any more content aimed at such users; rather I'm trying to signpost that the "tutorial" content is pitched at a level that probably won't be useful for maintainer onboarding or reference.

That said, in principle I'm not opposed to migrating that content to PyOpenSci, as long as folks in our community who rely on that content for their training needs are OK with such a move.