docs: improve docs about docs

- updates contributing file with a brief overview of kinds of
  user-facing documentation
- minor updates to book-building CI documentation

.github/check_book_update.sh

@@ -2,6 +2,13 @@
 #
 # Indicates whether the Programming Cryptol book PDF needs to be updated.
 #
+# Usage
+# This is primarily for use in CI. You can run it locally using the following:
+# > bash check_book_update.sh $(git diff --name-only --diff-filter ACDMRT master)
+#
+# If you are merging to a branch other than `master`, use that branch name
+# instead.
+#
 
 TEX_CHANGED=0
 PDF_CHANGED=0

.github/workflows/book.yml

@@ -1,12 +1,11 @@
 #
 # Checks that the PDF version of the Programming Cryptol book was updated
-# if any of its consitituent files were changed.
+# if and only if the constituent source files were changed.
 #
 
 name: Programming Cryptol PDF Update
 on: [pull_request]
 
-
 jobs:
     update_needed:
         runs-on: ubuntu-latest
@@ -20,4 +19,3 @@ jobs:
                 changed_files=$(git diff --name-only --diff-filter ACDMRT ${{ github.event.pull_request.base.sha }} ${{ github.sha }})
                 # This will fail if any files have spaces in the names.
                 bash .github/check_book_update.sh $changed_files
-

CONTRIBUTING.md

@@ -12,7 +12,7 @@ It describes our methods and practices for:
 - Testing and continuous integration
 - Organizing, branching, and merging this repository
 - Producing and publishing release artifacts
-- **TODO**: documentation
+- Documentation
 - **TODO**: feature/release planning, ticket assignment, etc
 
 This is a living document that is not (and possibly cannot be)
@@ -252,3 +252,47 @@ The release process is:
     - <cryptol-team@lists.galois.com>
     - <cryptol-users@community.galois.com>
     - @galois on Twitter (for major releases)
+
+# Documentation
+
+There are several overlapping forms of documentation for users of Cryptol:
+- the Programming Cryptol book;
+- the reference manual; and
+- other miscellaneous design docs and changelogs.
+
+These all live in the `docs/` directory.
+Some of these forms of documentation, including the book and some of the
+design docs, are housed here both in source (LaTeX source code, markdown
+files) and compiled (PDF) formats.
+
+Contributors should update the relevant documentation when they modify or
+extend user-facing features. Updates should be included in with pull requests
+that change the relevant feature. Contributors should re-build any PDFs or
+other artifacts when changing the corresponding source code.
+
+## Programming Cryptol
+The book lives in `docs/ProgrammingCryptol/`. There's a `Makefile` to build
+it. The compiled artifact lives in `docs/ProgrammingCryptol.pdf`; the
+`Makefile` does not build to that location, so updated artifacts need to be
+copied over. The CI aims to check whether the source and the artifact were
+updated in tandem (see `.github/workflows/book.yml`).
+
+## RefMan
+The reference manual lives in `docs/RefMan/`. There's a `Makefile` to build
+it locally. It's also built by the CI on pull request and deployed to the
+website (see `.github/workflows/docs.yml`), which allows users to browse
+manual versions corresponding to the `master` branch, any release, and any open
+PR. There are no artifacts that need to be manually maintained by contributors.
+
+## Other documentation
+There is a variety of other documentation, such as
+- The Cryptol preliminaries document (`docs/CryptolPrims.pdf`);
+- The Cryptol syntax guide (`docs/Syntax.pdf`);
+- The parameterized module guide (`docs/ParameterizedModules/`); and
+- other design docs and guides in `docs/`.
+
+Many of these are overlapping with or subsumed by the reference manual and the
+book. We recommend that contributors do not build on these documents and
+instead focus their efforts on the reference manual and the book. However, if
+the source for these is updated, the corresponding PDFs should also be updated
+using `pandoc` (see `docs/ParameterizedModules/Makefile` for an example).

docs/README.md

@@ -1,4 +1,15 @@
-Programming Cryptol README
+## Programming Cryptol README
+
+The Programming Cryptol book source code is in `docs/ProgrammingCryptol/`.
+It can be built using the `Makefile` in that directory.
+
+There is a pre-built PDF version of the book in this directory. Any updates
+to the source code must be accompanied by a corresponding update to the stored
+PDF. Developers should build the PDF locally (the default build location
+is `docs/ProgrammingCryptol/tmp/Cryptol.pdf`), copy it into this directory,
+and rename it to `ProgrammingCryptol.pdf`.
+
+### Other usage notes
 
 To use the check-exercises tool, invoke via `cabal v2-exec
 check-exercises --`. This requires the path to the LaTeX file to be
@@ -13,7 +24,7 @@ following commands:
   This is the markup equivalent of the `Verbatim` environment.
   However, it has the added effect of adding every line of the block
   to a list of commands to be issued to the cryptol REPL.
-  
+
 * `\replin|...|`
 
   Inline equivalent of `replinVerb` environment. Markup equivalent of
@@ -30,8 +41,8 @@ following commands:
 
   This is the markup equivalent of the `Verbatim` environment.
   However, it has the added effect of adding every line of the block
-  to the expected output of the preceding `\replin` commands. 
-  
+  to the expected output of the preceding `\replin` commands.
+
 * \replout|...|`
 
   Inline equivalent of `reploutVerb` environment. Markup equivalent of
@@ -49,13 +60,13 @@ following commands:
   Like `\replout|...|`, but is not rendered at all by LaTeX. This is
   for recording "hidden" output from the REPL that we don't want to
   include in the PDF.
-  
+
 * `\restartrepl`
 
   This has the effect of terminating the current input/output REPL pair. If
   there is input but no output, then instead of checking the output, the tool
   checks that the input does not raise an error.
-  
+
   This command is used to divide the REPL input/output pairs into distinct
   "blocks" that get submitted to the REPL independently. Therefore, this command
   should be called every time we are defining a new REPL pair; in particular, it