Misc doc updates

docs/README.md

@@ -4,7 +4,9 @@
 
 - [authentication.md](authentication.md) — pageserver JWT authentication.
 - [docker.md](docker.md) — Docker images and building pipeline.
+- [glossary.md](glossary.md) — Glossary of all the terms used in codebase.
 - [multitenancy.md](multitenancy.md) — how multitenancy is organized in the pageserver and Zenith CLI.
+- [sourcetree.md](sourcetree.md) — Overview of the source tree layeout.
 - [pageserver/README](/pageserver/README) — pageserver overview.
 - [postgres_ffi/README](/postgres_ffi/README) — Postgres FFI overview.
 - [test_runner/README.md](/test_runner/README.md) — tests infrastructure overview.

docs/glossary.md

@@ -26,8 +26,8 @@ A checkpoint record in the WAL marks a point in the WAL sequence at which it is
 NOTE: This is an overloaded term.
 
 Whenever enough WAL has been accumulated in memory, the page server []
-writes out the changes in memory into new snapshot files[]. This process
-is called "checkpointing". The page server only creates snapshot files for
+writes out the changes in memory into new layer files[]. This process
+is called "checkpointing". The page server only creates layer files for
 relations that have been modified since the last checkpoint. 
 
 ### Compute node
@@ -41,6 +41,15 @@ Stateless Postgres node that stores data in pageserver.
 Each of the separate segmented file sets in which a relation is stored. The main fork is where the actual data resides. There also exist two secondary forks for metadata: the free space map and the visibility map.
 Each PostgreSQL fork is considered a separate relish.
 
+### Layer file
+
+Layered repository on-disk format is based on immutable files.  The
+files are called "layer files". Each file corresponds to one 10 MB
+segment of a PostgreSQL relation fork. There are two kinds of layer
+files: image files and delta files. An image file contains a
+"snapshot" of the segment at a particular LSN, and a delta file
+contains WAL records applicable to the segment, in a range of LSNs.
+
 ### Layered repository
 
 ### LSN
@@ -102,6 +111,10 @@ Repository stores multiple timelines, forked off from the same initial call to '
 and has associated WAL redo service.
 One repository corresponds to one Tenant.
 
+### Retention policy
+
+How much history do we need to keep around for PITR and read-only nodes?
+
 ### SLRU
 
 SLRUs include pg_clog, pg_multixact/members, and
@@ -110,16 +123,6 @@ they don't need to be stored permanently (e.g. pg_subtrans),
 or we do not support them in zenith yet (pg_commit_ts).
 Each SLRU segment is considered a separate relish[].
 
-### Snapshot file
-
-Layered repository on-disk format is based on immutable files.
-The files are called "snapshot files".
-Each snapshot file contains a full snapshot, that is, full copy of all
-pages in the relation, as of the "start LSN". It also contains all WAL
-records applicable to the relation between the start and end
-LSNs. 
-Each snapshot file corresponds to one 10 MB slice of a PostgreSQL relation fork.
-
 ### Tenant (Multitenancy)
 Tenant represents a single customer, interacting with Zenith.
 Wal redo[] activity, timelines[], snapshots[] are managed for each tenant independently.

docs/sourcetree.md

@@ -13,7 +13,7 @@ Intended to be used in integration tests and in CLI tools for local installation
 Documentaion of the Zenith features and concepts.
 Now it is mostly dev documentation.
 
-`monitoring`:
+`/monitoring`:
 
 TODO
 
@@ -72,9 +72,9 @@ The workspace_hack crate exists only to pin down some dependencies.
 Main entry point for the 'zenith' CLI utility.
 TODO: Doesn't it belong to control_plane?
 
-`zenith_metrics`:
+`/zenith_metrics`:
 
-TODO
+Helpers for exposing Prometheus metrics from the server.
 
 `/zenith_utils`: