reorganize to clarify branistorming + resources

Includes part of #110

README.md

@@ -1,21 +1,43 @@
-This repository, inspired by the Rust project's RFC process, is
-intended to serve as a point of discussion for the design of Racket 2.
+This repository is for brainstorming and discussion about the design
+of a new language that is based on Racket.
 
-Please participate by commenting on pull requests and issues. Please
-post RFCs by forking and copying `0000-template.md`, which is based on
-the corresponding file in the Rust project.
+# Resources
 
-# Relevant mailing list posts
+* A summary of [possible goals](resources/goals.md)
 
-* [Racket2 and
-  syntax](https://groups.google.com/d/msg/racket-users/3aIPOGbGgmc/A4HHSbdxAwAJ)
-  from Matthew Flatt 2019/07/15
-* [Racket2
-  possibilities](https://groups.google.com/d/msg/racket-users/HiC7z3A5O-k/XPR2wbSJCQAJ)
-  from Matthew Flatt on 2019/07/20
-* [Clarify project policy on Racket2 syntax](https://groups.google.com/d/msg/racket-users/9Eh9H1Jt28Q/JXyDBfFrAgAJ)
-  from Matthew Flatt on 2019/08/14
+* References to some [mailing list discussion](resources/refs.md)
 
-# Resources
+* A summary of [potential syntax guidelines](resources/syntax-considerations.md)
+
+* An index of syntax [prior art](resources/prior-art.md)
+
+# Issues as a Wish List
+
+GitHub **issues** for this resposistory represent a kind of wish list.
+Post there for an idea about some way that you think a new language
+should be different than the current Racket language. Discuss other
+suggestions there.
+
+# Pull Requests as Draft Proposals
+
+GitHub **pull requests** for this repository can represent more concrete
+proposals. Proposals here do not have to be exhaustive, but they
+should be concrete enough to enable discussion of the pros and cons of
+a specific solution. There can and should be muliple conflicting
+proposals for any particular problem or direction, especially at
+first. The intent is to enable brainstorming and discussion toward a
+future, more-complete proposal.
+
+To make a draft proposal, start with "template.md" and create either a
+new ".md" file or a subdirectory containing a ".md" file and other
+supporting material (such as an implementation).
+
+# Pull Requests as Resource Updates
+
+GitHub **pull requests** for this repository can also be suggestions
+to update resources listed above. These resources are intended to be
+uncontroversial summaries, although they may point toward
+controverisal or conflicting perspectives.
 
-* An index of [prior art](prior-art.md) on syntax
+For these kinds of pull requests, please include "[resource]" at the
+start of the pull request title.

resources/goals.md

@@ -0,0 +1,32 @@
+# Motivation
+[motivation]: #motivation
+
+This document is intended to distill the main objectives of the project as explained in various threads and provide a resource to help orient discussion. It will evolve with the discussion.
+
+Issues and pull requests are expected to refine and elaborate points brought up in this document.  Similar to [syntax considerations](syntax-considerations.md), this should be considered a living document useful mostly for flushing out questions and reactions.
+
+This document, or the concepts in it, could also be used to help newcomers quickly orient themselves to some goals that may not have been apparent in the initial e-mails.  For a more detailed discussion with more nuances, it's still useful to read the full threads in [prior art](prior-art.md) (among others).
+
+# Goals List
+[goals-list]: #goals-list
+
+* more generics
+* more consistency
+* lower barriers of entry
+* extend smooth, fine-grained language extensibility to a broader set of syntaxes
+* make backwards-incompatible changes that reflect newer thinking (e.g., structs)
+
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+* What is the framework for bringing this from abstract goals to concrete steps?  What about even more abstract/higher level goals?
+* Should there be "sacred cows" or constraints in this document?
+* What does "lower barriers" mean?  What does "programmers generally" mean, given how heterogeneous that group is?  HOW heterogenous is the group?  (What would lower barriers *for whom*?)
+* What are specific obstacles teachers have had?
+* How much do we want to reach out to "non-programmer" programmers?
+* Are there particular concepts we want to encourage/discourage?  Lessons we want programmers to learn?
+
+Potentially relevant but outside the scope of this document:
+* How much community support is available for tooling, etc.?
+* How extensive will the interoperability between Racket2 and #lang racket be? (This is not just about syntax!)
+* What will be the relationship between Racket2 and the existing #lang racket?

resources/refs.md

@@ -0,0 +1,12 @@
+
+# Relevant mailing list posts
+
+* [Racket2 and
+  syntax](https://groups.google.com/d/msg/racket-users/3aIPOGbGgmc/A4HHSbdxAwAJ)
+  from Matthew Flatt 2019/07/15
+* [Racket2
+  possibilities](https://groups.google.com/d/msg/racket-users/HiC7z3A5O-k/XPR2wbSJCQAJ)
+  from Matthew Flatt on 2019/07/20
+* [Clarify project policy on Racket2 syntax](https://groups.google.com/d/msg/racket-users/9Eh9H1Jt28Q/JXyDBfFrAgAJ)
+  from Racket project leadership on 2019/08/14
+∑

resources/syntax-considerations.md

@@ -0,0 +1,28 @@
+# Motivation
+[motivation]: #motivation
+
+This document is meant to facilitate the discussion around syntactic principles by providing a record of considerations that have been brought up.  The intent is to be usable both as a checklist to help in discussing specific proposals and also as a starting point for developing and refining principles in the future.
+
+
+# Considerations List
+[considerations-list]: #considerations-list
+
+* familiar expectations
+  * US high school algebra
+    * infix operators
+    * algebra-style function notation
+    * parens can be used for grouping
+* flexible
+* clean / not "noisy"
+* dependent on advanced tooling/editor support
+* easy to rearrange chunks of code
+* distinctive
+* tree resemblance
+* uniformity vs texture
+* macros / language extensions feel natural next to existing forms
+* syntax leads to "syntax patterns" and "syntax templates" that are easy to use for macro writers
+* should be easily readable and editable outside of "your favorite editor"
+  - users (beginners in particular) should not need to learn keybindings or advanced editor features to effectively edit code. Editing code is not easy if it requires you to use `paredit`, for instance.
+  - users (beginners in particular) should be able to read code in various environments, like GitHub and codeblock embeded in Markdown. Matching parens is not easy if it requires you to use rainbow parens, for instance.
+
+∑∑