The Future of the PureScript Book

#1

Hey all,

As some of you know, with Phil’s go-ahead, I began a rewrite of Phil’s PureScript book after 0.12 was released because Effect was introduced, but Eff was used throughout. I also introduced psc-package instead of pulp/bower. At the time, I had a long commute via train, so I had extra time to commit to this, but now I don’t, so I thought I’d solicit volunteers to help finish it and start a discussion on what to do with the final product.

The first 9 chapters of the book are updated to 0.13/psc-package. I completely rewrote the end of chapter 8, and the result is pretty bad. I’m not a good writer, and there are some opinions in there that I’m pretty sure many of you would frown upon (see the discussion of MonadError at the end), so I think it needs a critical eye and/or a better writer. It could probably be made into two chapters and Chapter 11 Callback Hell could be where the Aff monad is introduced.

Additionally, spago should definitely replace psc-package, which would require an update to each chapter (shouldn’t take more than 30 mins/chapter).

Then I think it would make a lot of sense to merge this into purescript-contrib (with Phil’s go-ahead of course).

Thoughts?

12 Likes
#2

First off, I’d just like to say thanks for all of your hard work getting the book updated!

I am very interested in helping to complete the rewrite. I found the book to be a very valuable resource when I was first learning PS/FP, and I want people to be able to continue to find value in it.

I’d imagine many people use the book as their first exposure to PS (I know I did) and so I think moving it to spago would help reduce friction with respect to getting everything up and running. I second moving the book to use spago.

I’ll get in touch with you and take a look at the status of the repo soon!

6 Likes
#3

I’m not ruling out the possibility of updating the book, but I also don’t have any real plans to do it right now. If there are ever concrete plans for a 1.0 version of the compiler, then I would definitely like to update the book and think about making print copies available.

That said, I think it’s great that the book is still being updated, so thank you for that! That was definitely part of the original intent of using a creative commons license on the material. So as long as the terms of the license are observed, I’m happy to see a version developed, on purescript-contrib or elsewhere.

5 Likes
#4

It’s probably another topic for discussion altogether, but I’d really like to see a version 1.0 declared (or at least planned for the near term), specifically with no new features over what’s currently in 0.13.x. I chime in with this opinion every once in a while, and invariably get disagreement, but I do wish it would seriously be considered.

3 Likes
#5

Thanks for starting the discussion @dtwhitney!

I believe it would be nice to have a book along the lines of “The Rust Programming Language” book. A book that is the de facto book when picking up the language. Phil’s book is already this. It would be nice to have it under the PureScript organization such that it is easy to contribute to and hopefully keep up to date.

As I learn the language I’m willing to make some contributions here and there but I don’t think I’m able to lead the effort.

1 Like
#6

Yeah probably better to start another topic/discussion, but it would be nice to have Phil update the book :slight_smile:

#7

I thought I’d bring this up because it does somewhat relate. I think the larger question here is “What are the main learning resources the community will provide, so that new learners can get a solid foundation quickly?” Officially, it’s the PureScript book. However, I’ve also written my purescript reference learning repository.

Thus, how should these two resources relate, if any?

Currently, they are separate projects. Should things continue as that? Or should there be more integration between the two? The resources take two different approaches to try to achieve similar goals, so I’m not sure that they should. However, I thought I’d bring it up for discussion.

1 Like
#8

To be fair, I’m not sure what 1.0 would give you if it doesn’t also apply to the ecosystem. A large part of updating the book was Effect, and I also think React changes.

1 Like
#9

I didn’t know about your repo. It’d definitely be nice to have it included as a learning resource. Where are these decisions typically made? Github issues?

#10

IMHO 1.0 would be great even if it were merely symbolic. It’s a signal that PureScript is working and usable in production. I realize I’ve 0 contributions to the PS compiler, so I don’t really get a voice in that decision, but as someone who has taken the “risk” of using PureScript, it would be nice to see the pool of adopters grow.

1 Like
#11

Oh, I’m actually surprised to hear that. It’s already mentioned in the documentation repo’s Learning Resource’s third bullet point. I’ve also made announcements regarding it at various times on this site, too.

As for decisions, I have no idea. I opened an issue for adding my repo in the documentation repo. I then opened a PR for it.

Actually, Harry left a comment that is worth quoting below:

Sorry for the delay in responding. The reason it’s taken a while is that before linking to things, I’d really want to make sure we’ve had a good look at them first, and your repo has a decent amount of stuff in it.

I’m happy to put links to unofficial documentation resources in here, but I’d prefer that we clearly separated them from any official documentation and added a note to clarify that they are unofficial.

Content from other people’s projects can be referenced by contributors to this project, when and if that happens. ~Alex

I’m not super keen on this, as it happens; we have enough trouble keeping links between official resources alive as it is, and any references to unofficial resources are even more likely to change under us.