Prepare docs for initial release

README.md

@@ -1,45 +1,67 @@
 # Jacquard
 
 Jacquard is a Java autograder developed at Northeastern University
-with Gradescope integration.
+with Gradescope integration. It has been used at multiple universities.
 
 ## Features
 
-* Syntax-based analysis using [JavaParser](https://github.com/javaparser/javaparser)
 * Static analysis with [Checkstyle](https://checkstyle.org/) and
   [PMD](https://pmd.github.io/).
-* Test coverage and cyclomatic complexity measurement with 
+* Syntactic analysis using [JavaParser](https://github.com/javaparser/javaparser)
+* Test coverage and cyclomatic complexity measurement with
   [JaCoCo](https://www.jacoco.org/jacoco/).
 * Unit testing with [JUnit 5](https://junit.org/junit5/), including:
-  * running staff tests against student code
-  * running student tests against
+    * running staff tests against student code
+    * running student tests against
+        * student code
+        * intentionally buggy staff-written code
+        * correct staff-written code
+
+## Examples
+
+The best way to learn Jacquard is to review the examples, which include video explanations.
+
+You should start with [Jacquard Example 0](https://github.com/jacquard-autograder/jacquard-example0), 
+which shows how to grade based on Checkstyle, PMD, and JUnit 5 tests.
+
+[Jacquard Example 1](https://github.com/jacquard-autograder/jacquard-example1) adds syntactic analysis based on 
+the parse tree, such as whether students use certain language features and methods.
+
+[Jacquard Example 2](https://github.com/jacquard-autograder/jacquard-example2) demonstrates
+* Changing the default configuration values:
+  * visibility level of results
+  * timeouts
+  * language level
+* Running Checkstyle and PMD on multiple student files
+* Measuring code coverage of student tests
+* Running unit tests on student code
+* Fine-grained control of visibility
+* Cross-testing, i.e., running student tests against
     * student code
-    * intentionally buggy staff-written code
-    * correct staff-written code
+    * correct code
+    * buggy code
 
-For more information, see [Jacquard Examples](https://github.com/espertus/jacquard-examples).
+Example 2 does not depend on Example 1, which may be skipped if you are not interested in
+syntactic analysis.
 
-## User Information
+## Further Information
 
 * [Javadoc](https://jacquard.ellenspertus.com/)
 * [FAQ](doc/FAQ.md)
-* [User Guide](doc/Guide.md) (incomplete)
-* Examples
-  * [Jacquard Example 0](https://github.com/jacquard-autograder/jacquard-example0), which shows how to grade based on Checkstyle, PMD, and JUnit 5 tests.
-  * [Jacquard Example 1](https://github.com/jacquard-autograder/jacquard-example1), which adds grading based on the parse tree, such as whether students
-    use certain language features and methods.
-* Groups
-  * [jacquard-announce](https://groups.google.com/g/jacquard-announce)
-  * [jacquard-discuss](https://groups.google.com/g/jacquard-discuss)
+
+There are low-volume Google groups [jacquard-announce](https://groups.google.com/g/jacquard-announce)
+and [jacquard-discuss](https://groups.google.com/g/jacquard-discuss).
 
 ## Information for Contributors
 
 I welcome contributors, especially ones interested in integrating Jacquard with learning
-management systems (LMSs) and GitHub Class.
+management systems (LMSs) and GitHub Classroom. See [tips for contributors](CONTRIBUTING.md).
 
-See [tips for contributors](CONTRIBUTING.md).
+I also welcome [reports](https://github.com/jacquard-autograder/jacquard/issues)
+suggestions of how to improve Jacquard, the documentation, or examples.
 
 ## Credits
+
 Jacquard was influenced by Tim Kutcher's [JGrade](https://github.com/tkutcher/jgrade) and
 includes some of its `Visibility` and `GradedTest` code.