Revise wording to better convey the purpose of SPECs

[cbrnr]

Following up the discussion in scientific-python/lazy-loader#70, the way that SPECs are presented on the Scientific Python website can be misleading. It puts some (a lot of?) pressure on packages to adopt all SPECs, at least that's my impression. Since this is not intended, I think some modifications to the website might help clarify this. Here are some examples:

• The introductory sentence on the main SPEC page says: "SPECs provide operational guidelines for projects in the scientific Python ecosystem." If I develop a project in the scientific Python ecosystem, this sounds like I need to follow these guidelines. I guess the term "guidelines" is too strong, maybe "recommendations" or "suggestions"? I think it would be great if the first sentence already clarified that it's OK to not adopt any SPECs if it is not feasible, and that a project would still be part of the scientific Python ecosystem.
• The list of recommendations lists all SPECs as well as projects which have endorsed them. I think this is exactly the thing that's misleading projects into thinking that every good projects should strive to adopt as many SPECs as possible. After all, they get featured prominently on the website then. Honestly, I would remove all endorsing projects here, and maybe create a separate document, which describes projects that have adopted certain specs. This would give more room for presenting the pros and cons of each SPEC, and maybe make it clear that it's OK if a projects opts to not adopt a certain SPEC. It would also make it harder to see the amount of SPECs each project has adopted. Or maybe list projects which have supported a specific SPEC at the bottom of each SPEC page.
• On each SPEC page, and I'm now mainly talking about SPEC 1 (lazy loading), tone down the wording so that it is clear that no project has to adopt that SPEC. This also includes listing the pros and cons, which are already discussed, but maybe not prominently enough (only the advantages are listed near the top, the disadvantages get a short Caveats section much further into the text. For example, the introduction says: "This SPEC recommends a lazy loading mechanism—targeted at libraries—that avoids import slowdowns and provides explicit submodule exports." The libraries part is a bit unclear – when is a package a library? So after reading this, the message I get is that lazy loading is recommended. Period. I'd also include more caveats in this section (instead of footnotes), such as the rejection of the lazy import PEP, comments by some Python core devs why they are probably never going to include the mechanism, etc. This is extremely important information, which I had completely missed when we were discussing including lazy loading in MNE. At that time I just skimmed the SPECs page and thought "yeah, this sounds great, who doesn't want reduced import times for free?".

These are the things that I think could be easily improved. I can make a PR, but I think it makes more sense to discuss the changes here before that.

[jarrodmillman]

I am in general ok with this idea, but it is hard to say for sure without seeing a concrete PR to review. My main concerns are:

• The language should be terse, so people can read it.
• The language shouldn't become too legalistic.

It would also help it you (or anyone who sees this issue) could point at some concrete problems the SPECs are causing. For example, a PR discussion where someone is trying to pressure a project to adopt a SPEC or to follow a SPEC too exactly.

One idea I had was to use the 'Ecosystem Adoption' section of the SPECs to explain that the reasons and considerations a project may have when considering whether to adopt a SPEC. For example,

• https://scientific-python.org/specs/spec-0001/#ecosystem-adoption

One concern is these sections could get long and complicated if we try to list all the reasons a project might want to adopt or not adopt a SPEC or instances when a project that adopts a SPEC may for a specific release or set of releases want to fo something different.

[jarrodmillman]

The idea behind the SPECs is that many projects face similar concerns and now each project has to decide on what guidelines they should adopt for their individual projects. For example, maybe a project wants to implement lazy imports. Without SPEC 1, each project could survey other projects to see if or how they implemented it. I've done that many times for projects I work on. It seems like it would be nice to have that information in one place. I also am not going to read a long convoluted document. So I want something short and easy to follow.

We should say these are recommended guidelines. Not requirements. We've tried to do that, but it seems that people still view these as requirements or rules.

A recommendation is "a suggestion or proposal as to the best course of action, especially one put forward by an authoritative body." A guidelines is "a general rule, principle, or piece of advice." I think that makes sense, but maybe we can water it down more if people are still viewing these as laws or requirements.

[keewis]

English is a foreign language to me, but I had always assumed "guidelines" to be a weaker, looser form of "rules", something closer to advice than something to strictly follow.

In any case, I think the last paragraph in the "description" section of the purpose and process document is very clear:

Projects decide for themselves whether to adopt any given SPEC—often, this would be through team consensus. A SPEC may not be a good fit for every single project, and thus there is no expectation that all SPECs must be adopted by all projects. That said, SPECs serve their purpose through being adopted by several projects—and their authority stems from the extent to which they are.

However, I don't think everybody learning about the SPECs is going to read that document (and the link to it is easy to miss), so this could use some more visibility. Maybe by adding a explaining paragraph to the main page? In particular, both the above and a explanation of what "endorsed by" means would be important (contrasting it with "adopted by", which as far as I understand it is something very different).

I don't think renaming "guidelines" to "recommended guidelines" (or something similarly complex) would help a lot, since to me that would be much more confusing.

[tupui]

To me it's simple, we need to define the words like EU does for instance here: https://european-union.europa.eu/institutions-law-budget/law/types-legislation_en

Otherwise we are bound to an endless discussion around semantics, etc.

[cbrnr]

Let's not take this too far. I think what @keewis suggested is a good idea: include that paragraph on the main page, directly at the top. Otherwise, a recommendation is always something I should try to follow. Everybody likes to follow recommendations, right?

OTOH, this discussion revolves only around SPEC1 (lazy imports), so maybe this "recommendation" could be treated separately? E.g. a category "special-purpose SPECs for very specific use cases" (of course this shouldn't be the literal title)? All other SPECs can be recommended to any project in contrast to this one.

[jarrodmillman]

OTOH, this discussion revolves only around SPEC1 (lazy imports), so maybe this "recommendation" could be treated separately? E.g. a category "special-purpose SPECs for very specific use cases" (of course this shouldn't be the literal title)? All other SPECs can be recommended to any project in contrast to this one.

It applies to all the SPECs. I don't use SPEC 0 for all projects. For example, the lazy_loader package doesn't follow SPEC 0. It still supports Python 3.7.

The SPECs are meant to be basic recommendations. Each project will always need to consider when to follow them and when to not follow them. For SPEC 0, some of the endorsing core projects don't intend to follow SPEC 0 exactly.

[cbrnr]

I like the two PRs you made @jarrodmillman – simple and clean, but IMO they add what was missing before!

[jarrodmillman]

Closing since I think we have resolved this with #282 and #283. Feel free to reopen or open another issues, if I am mistaken. Thanks!!