Port Jordan's "Syntax" folder into this repo

[JordanMartinez]

Here's what I propose: port my entire Syntax Folder into this repo. (Note: the repo already has up-to-date syntax guide on the upcoming PS v0.14.0 release via the v0.14.0-syntax branch).

Here are the benefits:

• the entire language's syntax (at least as far as I know) is already documented in a very clear and readable way.
• the compiler is already being used to verify that the syntax is valid. As a result, it's easy to identify syntax that needs to be updated when breaking changes are released
• new learners will discover this folder's contents sooner and have a better learning process / new user experience

The costs:

• this repo seems intended primarily for a brief quick-start guide. Porting something this large into this repo could very well go "outside the scope of this project." (I can't recall if that's the reason why this hasn't been done before)
• my explanations would need to be reviewed. While most are true, I imagine people would bikeshed over the exact wording that should be used to explain something as there very well might be nuances that I have failed to capture or incorrectly communicated.
• increased maintenance burden. The compiler would reduce this maintenance, but explanations would still take time to review. Moreover, each PS release that includes breaking changes would add this additional 'to-do' onto an already large list.
• License conflicts. This repo uses CC-BY-SA-3.0. My repo uses CC-BY-SA-4.0.

[milesfrain]

I find the language folder in this docs repo (with a few .md files) much easier to consume than clicking though a tree of interleaved .purs and .md files.

I'd prioritize ease-of-reading over ease-of-maintaining, but getting both is ideal. Can we find a way to keep compiler verification, while still letting the docs be easy to read and navigate? Maybe something like mdBook anchors? Is this compatible with any of the ideas proposed in #344?

[JordanMartinez]

Can we find a way to keep compiler verification, while still letting the docs be easy to read and navigate? Maybe something like mdBook anchors?

Yeah, something like that is what I had in mind.

[cheery]

I've been thinking of this problem. Already a small fix on the documentation page could really help here. How about grouping the references together? Eg. When you now got "Learning" subheading, split it into "Books", "Language References", "Short posts". This way the next depth-first-batman doesn't go "OOK REFERENCE" and hit the Language reference -link before figuring there's more of them. For extra oomph put in "If the main reference ends up not answering what you're looking for, try the others as well".

Some benefit of doing it this way would be that Jordan can continue working on his material without needing movement to official documentation, which obviously grows as he studies on it, and the structure he has chosen would be good for what he's doing.

The downside to this is that the main language reference grows slower. But then, people could be less stressed and quality of that documentation could end up better because of it.

[JordanMartinez]

How about grouping the references together?

While that might clarify some things, I think the issue is a bit more nuanced than that. When I go to the Readme of this project, there are a TON of possible links I could click. That's not a bad thing, but a new learner is less likely to discover my repo. Even if they do, it's not easily navigable as Miles pointed out above.

[hdgarrood]

I think it might be helpful for me to lay out what I consider the scope of this repository (or, at least, of the language directory) to be in more detail. I think the language directory should fit into the 'reference' category in the documentation system described by Divio - that's why it's called the "language reference". That is, it should not be aimed at beginners, but rather people who already have at least a vague idea of how the things it describes work. It shouldn't go into a great amount of detail to discuss what's possible or recommend ways of solving common problems, but rather just describe what the language provides and how it works. The reason we need documentation in this style is that we need to have something to point to when an intermediate user comes across a situation where something doesn't work as they expected, so that we can work out whether it's a bug or intended behaviour. It's particularly important to have in the context of discussing changes to the compiler or language, so that we can see how things are supposed to work to avoid breaking things accidentally.

This repository grew out of a wiki which anyone could edit, which means that the structure is not great - there's definitely overlap in some places, especially between Records and Syntax. I've been meaning for a while to go over the whole thing and try to restructure it so that it's easier to find things and to avoid accidentally introducing overlap when editing. I've also been meaning for a while to try to transfer the language reference part back to the compiler repository, as I think the compiler and the language reference should ideally be developed in tandem. At the moment it's far too easy to add a feature in the compiler and forget to update the language reference. Putting the language reference inside the compiler repo also allows us to version them together, so that people can easily look at older versions of the language reference if they're using an older compiler.

I'm not sure exactly what the implications of this are for the idea of porting the Syntax folder into this repo, but I'm hoping that laying this out clearly might make it a bit clearer how we could proceed.

[JordanMartinez]

First, thank you for taking the time to respond in detail, @hdgarrood.

This repository grew out of a wiki which anyone could edit, which means that the structure is not great - there's definitely overlap in some places, especially between Records and Syntax.

Thank you for providing this history. It gives insight as to why the repo is structured this way.

I think it might be helpful for me to lay out what I consider the scope of this repository (or, at least, of the language directory) to be in more detail. I think the language directory should fit into the 'reference' category in the documentation system described by Divio - that's why it's called the "language reference". That is, it should not be aimed at beginners, but rather people who already have at least a vague idea of how the things it describes work. It shouldn't go into a great amount of detail to discuss what's possible or recommend ways of solving common problems, but rather just describe what the language provides and how it works.

My Syntax folder is more like a very large Tutorial on PureScript's syntax: the later parts build on top of the earlier parts and it is geared heavily towards beginners. At the very least, this clarifies the different purposes behind this repo's language reference and my Syntax folder.

The reason we need documentation in this style is that we need to have something to point to when an intermediate user comes across a situation where something doesn't work as they expected, so that we can work out whether it's a bug or intended behaviour. It's particularly important to have in the context of discussing changes to the compiler or language, so that we can see how things are supposed to work to avoid breaking things accidentally.

It sounds like the language reference exists primarily for core contributors to the PureScript language and people already familiar with the language. It was my understanding that this repo was more for new beginners who want a quick overview of the syntax and other PureScript-related things. Is that clarified anywhere in this repo?

I've also been meaning for a while to try to transfer the language reference part back to the compiler repository, as I think the compiler and the language reference should ideally be developed in tandem. At the moment it's far too easy to add a feature in the compiler and forget to update the language reference. Putting the language reference inside the compiler repo also allows us to version them together, so that people can easily look at older versions of the language reference if they're using an older compiler.

That makes a lot of sense! Would any part of my Syntax folder or some modification of it help to achieve or reduce the amount of work needed to achieve these goals?

I'd like to also consider another way forward, whether the Syntax folder helps the above goals or not. What if the Syntax folder was turned into its own repository and moved under the purescript organization? It might have the name purescript/syntax. Thoughts?

[hdgarrood]

It sounds like the language reference exists primarily for core contributors to the PureScript language and people already familiar with the language. It was my understanding that this repo was more for new beginners who want a quick overview of the syntax and other PureScript-related things. Is that clarified anywhere in this repo?

I don't think that's clarified in this repo, no. That would definitely be a good thing to clarify. Just to be absolutely clear, though - I'm only talking about the language/ directory, nothing I said above applies to anything else in this repo. I think most of the rest of what's in this repo is (or should aim to be) more beginner-appropriate.

Would any part of my Syntax folder or some modification of it help to achieve or reduce the amount of work needed to achieve these goals?

I can't immediately see how it would - the styles are of course quite different, and I think the style that the language reference currently has is preferable for reference documentation. Your Syntax folder may be useful for identifying gaps, although I think I personally would prefer to read through the compiler source code if I was trying to identify gaps.

What if the Syntax folder was turned into its own repository and moved under the purescript organization?

Having a repository just for syntax documentation aimed at beginners seems a little odd to me - I think beginners might not be able to tell the difference between a problem they're having arising from a misunderstanding of the language syntax versus a problem arising from a misunderstanding of something else about the language, so if syntax is documented separately from other things, that might make it harder for people to know which resource they should be looking at.

[JordanMartinez]

I don't think that's clarified in this repo, no. That would definitely be a good thing to clarify. Just to be absolutely clear, though - I'm only talking about the language/ directory, nothing I said above applies to anything else in this repo. I think most of the rest of what's in this repo is (or should aim to be) more beginner-appropriate.

I've opened #348 to address this point.

Having a repository just for syntax documentation aimed at beginners seems a little odd to me - I think beginners might not be able to tell the difference between a problem they're having arising from a misunderstanding of the language syntax versus a problem arising from a misunderstanding of something else about the language, so if syntax is documented separately from other things, that might make it harder for people to know which resource they should be looking at.

That's a good point and I think I see the nuance you're describing better. To restate what you're saying... Let's say someone is learning PureScript and they get a compiler error. There are generally two possible reasons why that error occurred. Either the learner did not use correct syntax (for example, wondering why foo :: a -> String doesn't work because they don't know that it needs a forall a.) or the learner misused a value or function in some expression (for example, getting a type unification error because they passed a String to a function that expects an Int). Improving, clarifying, and/or expanding this repo's syntax documentation won't necessarily solve that problem.

---

Changing topics, a few other thoughts have come to mind after I opened this issue. First, if I did port the Syntax folder to this repo, it would remove an important part of my repo and fragment that learning resource. I believe this would actually be undesirable. One of the main benefits of that repo is that you get all of it in one centralized repo rather than having to hunt for things across multiple repos. I think that alone is reason enough for me to close this issue.

Second, when I reconsider my motivation for porting the Syntax folder here, I think it was to remove some of the "competition" for a new learner's attention. In other words, the documentation repo appears on the PureScript website with the description of "the central place where you can find articles, in-depth learning resources for beginners, and more" (emphasis mine). This seems to imply a couple of things:

• the intended audience is beginners.
• the documentation has everything one might want and is comprehensive (or at least mostly comprehensive)
  , it's got the "official" stamp by appearing on the website.

Since this repo's Readme's Learning section includes the language folder, this is my imagination for what happens:

• a beginner goes to the PureScript website, which highlights both the Book and this documentation repo
• a beginner starts reading through the Book. Somewhere along the way, they start having questions about the language's syntax because the Book, in an attempt at making progress, doesn't fully explain something. (And to clarify, I don't think the Book should.)
• a beginner remembers that the documentation repo exists and checks it out.
• a beginner either sees the language folder, which appears before the Readme file's content appears on the page and clicks on that, or sees the "Language Reference" link in the Learning section and clicks on that. The reference answers some of their questions, but it still leaves them a bit confused because they assume that this folder's content is comprehensive and for beginners.
• at this point, a beginner might try my repo's link or ask questions on Slack or Discourse

If the above timeline is accurate, perhaps #348 will help resolve part of this issue.

Third, the two main issues with my repo, as Miles and others have brought up multiple times, is that 1) it's not easy to find and 2) it's not easy to navigate. Porting this folder to this repo would make it easier to find as it would appear as an "official" learning resource, but it still wouldn't be easy to navigate. If I fixed both of those problems by using something like mdbook, it might address the "new learner's attention" issue I described above without needing the "official" stamp.

Thoughts?