minor changes to docs

Author: jodersky

book/src/README.md

@@ -18,7 +18,7 @@ In a terminal:
 
 - Simple interfaces
 
-  - Top-level, annotation-based.
+  - High-level, annotation-based, CLI generator.
 
   - Lower-level interface inspired by the
     [argparse](https://docs.python.org/3/library/argparse.html) package from Python.
@@ -49,5 +49,6 @@ available on maven central under the coordinates:
 
 | Channel | Links |
 |---------|-------|
+| Forum | [GitHub Discussions](https://github.com/jodersky/scala-argparse/discussions) |
 | Chat | [![discord](https://img.shields.io/badge/chat-discord-blue)](https://discord.gg/usj9DC8FDN) [![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://crashbox.zulipchat.com/#narrow/stream/330744-argparse) |
 | Issues | [GitHub](https://github.com/jodersky/scala-argparse/issues) |

book/src/annotation.md

@@ -8,10 +8,9 @@ such as help messages and bash completion.[^1]
     3.3.0), you will need to write a tiny boilerplate snippet as shown in the
     introductory example.
 
-Note: the generated code uses a lower-level interface, which can also be
-directly used for more flexibility. It is suggested that you [read the
-tutorial](./ll/index.html) in any case, for further understanding of how
-argument parsing works at a lower level.
+The generated code uses a [lower-level interface](./ll/index.html), which you
+can also use directly if you would like more flexibility than what the
+auto-generated CLI provides.
 
 ### Parameter Mapping
 
@@ -46,10 +45,6 @@ for many types out-of-the-box. Some examples:
 - various `java.time` date types
 - `key=value` pairs of other supported types
 
-The mechanism in which command line arguments are converted to Scala types is
-highly customizable and [new types can easily be
-added](./ll/cookbook.md#adding-support-for-a-new-type-of-parameter).
-
 E.g.
 
 ```scala
@@ -60,6 +55,10 @@ E.g.
 {{#include ../../examples/annotation-types/src/shell.txt}}
 ```
 
+The mechanism by which command line arguments are converted to Scala types is
+highly customizable and [new types can easily be
+added](./ll/cookbook.md#adding-support-for-a-new-type-of-parameter).
+
 ### Parameter Overrides
 
 The generated command line parameters can further be customized by annotating
@@ -129,9 +128,9 @@ of parameters. See the `git` or `docker` tools for some such examples.
 
 In scala-argparse, nested commands use the same mechanism as single, top-level
 commands, with one small twist: instead of annotating a *method* with
-`command()`, you annotate a *class definition* (or a function that returns an
-instance of an annotated class). This can be done recursively, and classes can
-declare parameters which can be referenced by child commands.
+`command()`, you annotate a *class definition* (or a method that returns an
+instance of a class containing other commands). This can be done recursively,
+and classes can declare parameters which can be referenced by child commands.
 
 E.g.
 
@@ -164,7 +163,7 @@ Any program that uses scala-argparse automatically gets:
 
 - Now that you know the high-level API, check out the [lower-level
   API](./ll/index.html), which underpins the former and can be helpful for
-  understanding cusomizations.
+  understanding customizations.
 
 - Read the API docs. Start with the [`argparse.default`
   bundle](javadoc/api/argparse/default$.html).

book/src/ll/tutorial.md

@@ -103,7 +103,7 @@ Here is what is happening:
   specify it). Specifying anything else results in an error. But even then, we
   do get a useful usage message, also for free.
 
-## Introducing Required Parameters
+## Required Parameters
 
 An example:
 
@@ -167,7 +167,7 @@ Following is a result of running the code:
 
 That went well. The program now even helpfully quits on bad input.
 
-## Introducing Optional Parameters
+## Optional Parameters
 
 So far the parameters that we have specified were required. Let's look at how we
 can make an argument optional.
@@ -194,7 +194,7 @@ Here is what's happening:
 - The default value will be used if the argument is not encountered on the
   command-line.
 
-## Introducing Repeated Parameters
+## Repeated Parameters
 
 An example: