It seems like we have an unspoken convention that, if you write a library, you sometimes have an examples folder that shows how to use that library to do various things.
I’ve been wondering whether those examples should instead be ported to the PureScript cookbook repo. I see pros and cons of both:
If they were ported, it would provide a centralized and therefore easy-to-find documentation on how to use a library. Moreover, since it’s tested via CI, we would know whether it still works or not (as opposed to a ReadMe file’s code content that could work but might not). I think this would be a big win for new users.
However, this idea seems to come with a big loss to library authors. When making changes/improvements to a library, it can be helpful to quickly test out your code via the examples you have in mind. In other words, running spago build vs spago -x examples.dhall build is very easy. If the porting did occur, one would have to have a local copy of cookbook, mess with make and the packages.dhall file to use their local version of a package, and potentially deal with version conflicts involving npm dependencies.
What are your thoughts on the matter? The larger question in all of this is, "Where does the cookbook fit in with the rest of our documentation (i.e. the PureScript documentation repo, the PureScript book, Pursuit, various Discourse threads, other guides, my learning repo, etc.)?
I think the issue of CI is orthogonal, because library authors can definitely set things up so that code in their examples directory is testing in CI: I think all you have to do is to add a step spago build --path examples after the normal build step, so that your examples get built too. I’m also not sure either option necessarily results in examples being easier to find than the other: I think it’s reasonable for people to look at a particular library in the first instance to find examples of how to use that library.
I would suggest that library authors should keep whatever level of examples they feel is appropriate in their libraries - let authors make the call of how much example code they want to maintain. I also think duplicating examples between the cookbook and libraries is probably fine if we want to maximize the probability of people finding what they’re looking for. Maybe examples along the lines of “how to use libraries X and Y together” might be more appropriate for the cookbook repo in general, if privileging library Y in the docs for library X or vice versa might not feel appropriate?
I feel like one important thing to bear in mind is that a library repo will have a different set of people with the commit bit than the cookbook repo, and we shouldn’t necessarily expect authors to navigate contributing to a separate repository for publishing code examples which are “theirs,” at least in some sense.
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.
Thanks for the responses! You both provide excellent arguments against doing that. I was leaning that same direction as I was writing this post, but wasn’t aware of some of the arguments you mentioned when I wrote it.
My main motivation for discussing this was not wanting to take what others have done and duplicate it in the cookbook. For example, I recently ported all the component-style Halogen examples to their corresponding Hooks-style Halogen examples. I was wondering whether we should duplicate the Halogen repo’s component-style Halogen examples inside the cookbook or update the hook-style Halogen examples to link to the original examples. I don’t want to maintain the same Halogen recipe for both component-style and hooks-style recipes as it seems unnecessary.
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?
That’s another good point. I’d definitely like the cookbook to focus on two or more libraries integrating together to solve some problem than demonstrating how to use a library. However, I also realize that not all authors want to maintain a separate examples folder in their repo. For example, @thomashoneyman, should I port over the HalogenHooks versions of the original halogen examples to your hooks repo? I’m guessing you don’t want to maintain that large number of examples.
I would say most of the Halogen examples are not cookbook-worthy, as far as I understand when it comes to the purpose of a cookbook. They’re mostly designed to illustrate one particular aspect of Halogen, not necessarily solving “actual” problems.
The Hooks examples include several of the Halogen examples (but not all) and I’m open to adding more. Like the cookbook, it’s a balance between being sufficient without having too much redundancy.
Like @garyb said, not all Halogen examples are cookbook-worthy in that they’re contrived to show a specific feature or don’t represent a task you really want to do. They’re educational, like the cookbook, but not in the same way.
I’m open to porting any examples to the Hooks repo which demonstrate behavior not already demonstrated by existing examples. Event sources might be one such thing, and child components. But I don’t think the Hooks repo needs to have all the same examples as the Halogen repo.
Ultimately that’s a design question for the cookbook authors: what is the right scope for a recipe (not too basic, not too involved)? What is the right balance between quantity of recipes (for comprehensiveness) and keeping a manageable number (for maintenance and discoverability)? I don’t know the answers, and maybe this criteria will have to emerge over time as the cookbook develops, but I think they’re questions worth keeping in mind while working.