Documentation edits in preparation for alpha release (#691)

CONTRIBUTING.md

@@ -112,8 +112,7 @@ the same as a bug report. Just describe your idea in as much detail as you can.
 You are very much encouraged to help think about game design: how new
 language features, entities, devices, and world features should be
 added and changed, and how they all fit together to deepen the game
-and create possibilities of gameplay.  This aspect of the game is very
-much unfinished and will need a lot of work.  Take a look at the
+and create possibilities of gameplay.  Take a look at the
 [DESIGN](DESIGN.md) document in this repository for some overarching
 thoughts and principles about the design of the game.
 
@@ -237,8 +236,7 @@ suggestions.
   hand. PRs will be merged as a single squashed commit, using the
   title and description of the pull request, so make sure that they
   give a good overview of the content of the PR.  To merge a pull
-  request, (1) make sure it has at least one approving review, and
-  (2) add the `merge me` label.
+  request, just add the `merge me` label.
 
 More conventions will be added as we think of and/or come up with
 them!
@@ -268,8 +266,9 @@ fixed up later if necessary, and it's more important to help them feel
 welcome and that their contribution is valued.  More experienced
 contributors can be held to a higher standard.
 
-Having push access also means, of course, that you can push directly to
-`main`. You are welcome to do so for typos, small fixes, documentation
-improvements, and the like; for larger fixes, new features, _etc._ opening a
-pull request from a feature branch is still preferred, to give a chance for
-others to offer suggestions for improvement.
+Having push access also means, of course, that you can push directly
+to `main`. You are welcome to do so for typos, small fixes,
+documentation improvements, and the like; for larger fixes, new
+features, _etc._ you should still open a pull request from a feature
+branch, to give a chance for others to offer suggestions for
+improvement.

DESIGN.md

@@ -1,36 +1,55 @@
-A few principles to guide the development and design of the game.
+Here are a few general guiding principles behind the development and
+design of the game.
 
-- Above all, the game should be fun! (But it's OK if it's only fun to
-  a certain kind of nerd.)
+Fun
+---
 
-- The game is, first and foremost, a *programming* game, and it should
-  promote the exploration and use of various sorts of programming
-  abstractions.  In other words, it should reward finesse in writing
-  sophsticated robot programs, as opposed to e.g. throwing a ton of
-  robots at things by brute force (though it's OK if some brute force
-  is required as well).
+The game should be fun! (But it's OK if it's only fun to a certain
+kind of nerd.)
 
-- There should be multiple viable paths to upgrading and building more
-  abstractions.  In other words, we *don't* want a linear chain of
-  achievements, where you *must* enable language feature X in order to
-  obtain resource Y, which you need in order to enable language
-  feature Z, which you need in order to... and so on.  Some of this
-  will probably happen organically---it would probably be impossible
-  to enforce a strictly linear chain of achievements even if we wanted
-  to---but it's worth reflecting on explicitly.
+Programming
+-----------
 
-- Ideally, everything in the game---including both entities and
-  programming language features---should be discoverable just by
-  playing.  (This includes the possibility of having an in-game
-  tutorial to teach the basics first.)
+The game is, first and foremost, a *programming* game, and it should
+promote the exploration and use of various sorts of programming
+abstractions.  In other words, it should reward finesse in writing
+sophsticated robot programs, as opposed to e.g. throwing a ton of
+robots at things by brute force (though it's OK if some brute force is
+required as well).
 
-- The activities of adding more programming language features, adding
-  new kinds of entities and recipes, and adding new things to the
-  generated worlds are all inextricably linked, and should be done
-  deliberately.  It will probably require a lot of experimentation and
-  tweaking to balance things so that gameplay is interesting and
-  challenging but not overly difficult.
+Composability
+-------------
 
-- Don't provide complex built-in features; instead, provide simple,
-  fundamental, composable pieces out of which users can build the
-  complex features themselves.
+Don't provide complex built-in features; instead, provide simple,
+fundamental, composable pieces out of which users can build the
+complex features themselves.
+
+Open World
+----------
+
+There should be multiple viable paths to upgrading and building more
+abstractions, and multiple avenues for exploration.  In other words,
+we *don't* want a linear chain of achievements, where you *must*
+enable language feature X in order to obtain resource Y, which you
+need in order to enable language feature Z, which you need in order
+to... and so on.  Some of this will probably happen organically---it
+would probably be impossible to enforce a strictly linear chain of
+achievements even if we wanted to---but it's worth reflecting on
+explicitly.
+
+Discoverability
+---------------
+
+Ideally, everything in the game---including both entities and
+programming language features---should be discoverable just by
+playing.
+
+Balance
+-------
+
+The activities of adding more programming language features, adding
+new kinds of entities and recipes, and adding new things to the
+generated worlds are all inextricably linked, and should be done
+deliberately.  It will probably require a lot of experimentation and
+tweaking to balance things so that gameplay is interesting and
+challenging but not overly difficult or tedious.

README.md

@@ -12,7 +12,7 @@ complex programs.
 
 ![World 0 after scanning a tree and making a log.](images/tutorial/log.png)
 
-The implementation is still in an early stage, but these are some of the (planned) features:
+Features include:
 
 * Practically infinite 2D procedurally generated worlds
 * Simple yet powerful programming language based on the polymorphic
@@ -30,16 +30,14 @@ The implementation is still in an early stage, but these are some of the (planne
       without worrying about collecting resources.
     - There are also challenge scenarios where you attempt to program
       robots in order to solve pre-designed puzzles or challenges.
-    - Future versions might also have multiplayer modes, with co-op or
-      PvP play over a network...?
 
-Installing and Playing
-======================
+Installing
+==========
 
-Warning: Swarm is still in an early stage; it's missing many of the
-planned features, there is no winning condition, and the gameplay is
-not very deep yet.  But you can program cute little robots, and hey,
-that's all that really matters, right?
+Instructions for installing from a binary release will go here!
+
+Installing from Source
+----------------------
 
 **NOTE**: Swarm requires a POSIX-style environment that supports
 `terminfo`.  On Linux and OSX, the below instructions should work
@@ -47,7 +45,7 @@ natively.  On Windows, see [the comments on this GitHub
 issue](https://github.com/swarm-game/swarm/issues/53) for instructions
 getting it to work under the Windows Subsystem for Linux.
 
-The recommended way to install Swarm at the moment is as follows:
+To install Swarm from source:
 
 1. Clone the Swarm repository, e.g.
 
@@ -75,36 +73,19 @@ The recommended way to install Swarm at the moment is as follows:
 1. Have fun!
 
 
-Programming swarm
-=================
+Configuring your editor
+=======================
 
-Your base has a dictionary to store definitions, like this one:
-
-```
-def moveUntil : cmd bool -> cmd () = \predicate.
-  res <- predicate;
-  if res {
-    noop
-  } {
-    moveUntil predicate
-  }
-end
-```
-
-<sup>The indentation is not required but `;` is, as it is similar
-to Haskell `>>` - that is the command monad, which imperative
-programmers can ignore. :wink:
-</sup>
-
-This allows you to program robots to perform complicated tasks.
-
-While you can write commands and definitions like the one above
-in the REPL, swarm also has a editor support with highlighting
-and LSP integration:
+Although you can write commands and definitions directly in the Swarm
+REPL, once you get beyond the basics you'll probably want to use an
+external editor for writing Swarm programs.  Swarm has support for
+external editors with highlighting and LSP integration:
 
 ![Editor with problem popup](images/editor.png)
 
 See the `editors` folder for details on how to configure your editor.
+Currently, Emacs and VS Code are officially supported, but more can be
+added.
 
 Community
 =========
@@ -115,6 +96,6 @@ others in the community.
 If you want to contribute, you're most welcome!  There are *lots* of
 ways to contribute, regardless of your Haskell background.  For
 example, even someone with no Haskell experience whatsoever could
-still help with *e.g.* game design, playtesting, and level design for
-challenge mode.  Check out the [CONTRIBUTING](CONTRIBUTING.md) file
-for more specific information about how to contribute.
+still help with *e.g.* game design, playtesting, and creating
+challenges and scenarios.  Check out the [CONTRIBUTING](CONTRIBUTING.md)
+file for more specific information about how to contribute.