Thanks again for sharing the steps you took to figure this out on your own. This is valuable feedback on how folks can get stuck, despite doing a reasonable job consulting the available reference material (e.g. Pursuit and Docs repo).
Unfortunately, it seems like most of the resources expect you to read the book first, which can be a pretty significant initial time investment. We also don’t clearly state this as a prerequisite.
I think we should also enable the learn-from-examples approach by providing a better syntax reference. Perhaps we list symbols and keywords that are built into the language, along with links to where the reader can learn more.
For example:
| Symbol or Keyword | Used For |
|---|---|
do |
“do notation”(link) |
<- |
“do notation”(link), “pattern guards”(link) |
-> |
“basic functions”(link), “lambda functions”(link), “case expressions”(link) |
. |
“record access”(link), “generic functions / forall”(link) |
:: |
“type signatures”(link) |
\ |
“lambda functions”(link) |
_ |
“ignored type”(link), “anonymous argument”(link) |
I just pointed to the not-so-beginner-friendly language reference for a few of those links above. Ideally, we’d make this content accessible to beginners too by either:
- Add a link to a beginner’s guide in each section of the reference.
- Link to a beginner-friendly guide first, that then points to the reference.
- Keep both levels of detail in the reference, but start with a terse summary, and then follow-up with more descriptive examples further down in the page.
Maybe this symbol and keyword lookup can be built into Pursuit.
This video delivers a really excellent overview of important language concepts in a beginner-friendly way (including “do notation”). Note that we use pure instead of return.
I think the term pure is another source of confusion for beginners. When I first saw that keyword, I assumed it was making the returned value “more pure”, when in-fact the value returned is “less pure” by getting wrapped in an effect. I think a better keyword would have been something like box, which conveys the act of packaging the value and is a common analogy in FP.
There’s also a section on “do notation” in chapter 4 of the book, but I (and others) found this pretty confusing on the first read though. Proposing we move this material on array comprehensions outside of the critical path for beginners.