Remove link to Purescript by Example & emphasize Documentation repo

[JordanMartinez]

The basic problem: a beginner to PureScript has an initially-frustrating learning experience that is pointless because the language's website seems to indicate that the Book (Purescript by Example) is up-to-date. They don't realize this until the code does not compile or work as expected, sign up for the FP Slack or Discourse and get told otherwise.
If we clarified from the start that the book is outdated, it would greatly improve the learning experience and PureScript's reputation as a whole. Moreover, there are other learning resources that, though "unofficial," would still be helpful to the new learner overall if they were highlighted better as supplemental to the book.

(This is how I finish my comment below) I think the best short-term way we could help the learning experience is by

• taking down the link to the Purescript by Example book on the website (stops that initial frustrating learning experience since readers are not immediately aware that the book is outdated)
• update the site to emphasize the documentation repo as “the” place to go for learning resources
• add more context to the book’s link in the documentation repo (i.e. the book’s code is outdated, but the principles are still valid. See dwhitney’s fork of the book’s code. See Jordan’s learning repo for supplemental reading.) Unfortunately, I’m not sure whether linking to dwhitney’s fork will be done by that “official” repo because of copyright reasons.

Note: my learning repo is helpful but not a replacement for the Book. Rather, I consider it supplemental reading that is sometimes wrong (because I obviously do not know as much as Phil does).

For context, see PureScript documentation efforts. The important conversation is below:

The first answer for “a sense of a home base” of documentation isn’t the GH/purescript/documentation project. I wonder why that is

Here’s my thoughts on this matter:

• The PureScript website describes the documentation repo as a place “where you can find articles, tutorials, and more.” Most notably, it seems like a general “Here’s some ideas that are useful, but they are not start-to-finish explanations that make you productive in this language, especially if you’re a beginner.” Rather, that is achieved via the book, which is described as “The free PureScript By Example book contains several practical projects for PureScript beginners.” This description seems to indicate that one should start here rather than elsewhere. It’s got the official website linking to it rather than something else. It’s got the “By Example” title. It includes comments about ‘projects for beginners.’ And it’s free, so the initial investment is curiosity and time, not money.
• It’s only when one starts to encounter problems with the Book due to its outdated nature (and starts to experience “friction” in the learning experience) do they then look at the documentation repo, which further frustrates them because it is not a replacement for the Book. Likewise, my learning repo (which the documentation repo now links to thanks to chexxor’s follow up) is not a replacement for that book but does serve to supplement some of its ideas/explanations.
• I think the best short-term way we could help the learning experience is by taking down the link to the book on the website (stops that initial frustrating learning experience), update the site to emphasize the documentation repo as “the” place to go for learning resources, and add more context to the book’s link (i.e. the book’s code is outdated, but the principles are still valid. See dwhitney’s fork of the book’s code. See Jordan’s learning repo for supplemental reading.). Unfortunately, I’m not sure whether linking to dwhitney’s fork will be done by that “official” repo because of copyright reasons.

[justinwoo]

Just to echo, this is something Phil was also talking about doing because it makes for a frustrating experience for newcomers. And I think that over the last two years, the documentation repo actually has had a lot of content put into it that the book isn't the only source of information about things.

[hdgarrood]

I’m not sure if there are copyright issues with linking to dwhitney’s fork. The text of the book is CC BY-NC-SA 3.0 and the exercises are MIT; both of these permit redistribution of modified versions as long as you meet some simple requirements set by the terms (and these requirements are not at all onerous).

[JordanMartinez]

Just to echo, this is something Phil was also talking about doing because it makes for a frustrating experience for newcomers.

Mm.. I did not know about that. Last I heard/remember, Phil did not want to give up the copyright for the book in case he wanted to use it for something else in the future. However, I really don't remember why I though that.

I’m not sure if there are copyright issues with linking to dwhitney’s fork.

Also something I did not know.

[chexxor]

What should be the split between content on the PureScript website and content in the documentation project? I can think more about it later to be constructive, but raising the question now shouldn't hurt.