Document project scope

In #199 we discussed the scope of Try PureScript -- what its goals are, what its goals should not be, what sorts of features are acceptable, and so on.

The gist of it was that Try PureScript is a single pane for editing PureScript code + a single pane for showing output (whether a rendered UI or console output), and that any features outside of writing PureScript from the package set should be provided via the TryPureScript module so they can be used in main.

I think this is useful to document within this library so that new contributors can understand the scope and purpose of this project and to therefore open better issues and pull requests.

Here are some pertinent quotes:

...the SPA needs of try-purs are very conservative, and I think that's a good thing.

I consider it an anti-goal to iterate on try-purs to the point of being an IDE in the browser, and that we should focus on it being a small-demo showcase and way to share quick snippets. Not that something like that should not exist somewhere, just that I don't think that should be the goal of the core team infrastructure. As an example, Ellie exists for elm, and is able to iterate independently and grow based upon the creator's vision for editing and sharing Elm code, which is separate from the language infrastructure's development. The official demo case for TypeScript is very conservative, and is basically only console logging.

Additionally, I also consider it in an anti-goal for try-purs to be a beacon example for modern SPA development in PureScript. That's not to say that Halogen or React are bad choices or the wrong choices, just that I do not consider that to be a contributing factor.

My personal criteria are:

• It should build with stock tooling, and should not require npm dependencies and JS bundling step (we currently refer to global jQuery so we can load it from wherever).

• It should not require significant or controversial architecture decisions, to reduce bike-shedding and make it more likely for a hypothetical PR to go through.

• We should prioritize smaller bundles. We already have to ship a lot to load all the modules for running demos, so I think reducing as much overhead as possible in the actual application is desirable.

I consider "controversial architecture decisions" to largely mean fancy types like Run, Variant, Cofree, etc. That is, the goal is not to showcase all the fancy things you can do in PureScript, it should be very straightforward for someone to read, understand, and review.

I want to be clear that I don't necessarily consider Halogen or React to be immediately rejected on those terms, just that I think we should prioritize those points.

-- @natefaubion

Big 👍 to everything @natefaubion has said, especially the anti-goals.

-- @hdgarrood

I think the basic workflow for try-purs should stay as-is:

• A single editor for PureScript code
• A single pane to see the result

...I do not consider it in scope to include multiple modules, multiple language editors (HTML, CSS, and especially foreign modules), or anything outside of editing PureScript code. If we want to offer additional features, we should add them to the TryPurescript module so they can be invoked within main.

-- @natefaubion

I think this content can be trimmed a little and included in a "Project Scope" section in the readme. Alternately, we could create a new page of documentation meant for contributors, which both discusses some of the internal decisions (like how to manage the iframe) and also outlines the scope of features for the project.

Start by reading the README and the discussion in issue #199. Document the project's scope, goals, anti-goals, and feature boundaries in a Project Scope section or a contributor documentation page, while preserving the guidance about the TryPureScript module and internal decisions such as iframe management.