diff --git a/framework/generate.ts b/framework/generate.ts
index e2f84ef..c88af61 100644
--- a/framework/generate.ts
+++ b/framework/generate.ts
@@ -1,3 +1,8 @@
+// This file contains the main site generator build process.
+// By using `incr.work`'s ability to cache work between runs,
+// the site generator is very fast to re-run.
+//
+// See `watch.ts` for a live development environment.
 const { toRel, toAbs } = incr;
 const globalCssPath = toAbs("src/global.css");
 
diff --git a/framework/incremental.ts b/framework/incremental.ts
index c2d7dc3..525793e 100644
--- a/framework/incremental.ts
+++ b/framework/incremental.ts
@@ -1,4 +1,9 @@
-// Incremental compilation framework
+// Incremental build system using singleton state.
+// See `work()`, `compile()`, and `invalidate()` for details.
+//
+// All state is serializable to allow recovering state across sessions.
+// This framework special-cases the asset map, but is otherwise
+// agnostic of what it is a compiler for.
 let running = false;
 let jobs = 0;
 let newKeys = 0;
@@ -85,7 +90,7 @@ export function work<I, O>(job: Job<I, O>, input: I = null as I): Ref<O> {
 }
 
 export async function compile<T>(compiler: () => Promise<T>) {
-  ASSERT(!running, `Cannot run twice`);
+  ASSERT(!running, `Cannot run twice at the same time.`);
   try {
     running = true;
     ASSERT(jobs === 0);