I’m excited and encouraged to see the cookbook coming together. There’s a concerted effort from several contributors to have practical, well-organized examples of how to accomplish various tasks in PureScript using common libraries.
In my mind a cookbook serves a different purpose from library examples and tests.
First, it’s not necessarily run or written by the library authors (as Harry noted). Even if we wanted to encourage library authors to use the cookbook instead of adding examples to their repository (which I don’t think would be a good idea), we can’t enforce it in any way; I would expect that library authors organize their repositories as they see fit and if they want to contribute recipes to the cookbook then they can. In an ideal world the cookbook becomes a place for discovery and education and authors want to contribute recipes for their libraries (but don’t have to).
Second, library examples and tests are a convenient in-repo, (often) zero-dependency way to ensure that the library can be used the way the author envisioned and keeps compiling as the library API changes. For that reason, examples and tests may not match with the goals of the cookbook (which is an educational resource). That’s why so many libraries often have several very simple examples showing basic usage and then one or two complex examples that really stretch the library or show off the kitchen sink. The examples aren’t necessarily curated to be the best or right way to use the library or to have a high signal to noise ratio. The effort of maintaining examples in a library (as Harry also noted) puts extra pressure on this.
Letting library authors handle examples as they see fit is actually empowering for the cookbook, in my mind. It means the cookbook relies on fewer people (it’s not coordinating official examples for multiple libraries along with user-contributed additional recipes, for example). The cookbook can maintain fewer examples if it leaves the simple ones to the libraries themselves and focuses on the more practical, real-world examples. It can selectively copy the high-value examples it sees in its constituent libraries. If the cookbook authors think an example could be expanded on or made better then they don’t have to coordinate with the library author (who may have other motivations for why the example is written a particular way), they can just improve their version of it. Won’t the cookbook’s value be diminished if it is flooded with hundreds of small basic usage examples that could have just been in the library itself?
The cookbook is different from documentation like the PureScript documentation, the PureScript book, Pursuit, Discourse threads, long-form guides, and learning repositories because it’s light on teaching and explanations and heavy on demonstration. It’s different from example applications like Real World Halogen because recipes are more single-purpose. With that in mind I think it already fills an important niche without necessarily becoming more entwined with other projects.