diff --git a/doc.go b/doc.go
index 0cb1ada..7a53dee 100644
--- a/doc.go
+++ b/doc.go
@@ -11,10 +11,11 @@
 // `RecoverOrphans(".core/state/")`.
 //
 // Use `store.NewConfigured(store.StoreConfig{...})` when the database path,
-// journal, and purge interval are already known. Prefer the struct literal
-// over `store.New(..., store.WithJournal(...))` when the full configuration is
-// already available, because it reads as data rather than a chain of steps.
-// Use `store.WithWorkspaceStateDirectory("/tmp/core-state")` when the
+// journal, purge interval, or workspace state directory are already known.
+// Prefer the struct literal over `store.New(..., store.WithJournal(...))`
+// when the full configuration is already available, because it reads as data
+// rather than a chain of steps. Use
+// `store.WithWorkspaceStateDirectory("/tmp/core-state")` only when the
 // workspace path is assembled incrementally rather than declared up front.
 //
 // Usage example:
diff --git a/store.go b/store.go
index 8e26bfb..3bb3dd9 100644
--- a/store.go
+++ b/store.go
@@ -174,6 +174,8 @@ func WithJournal(endpointURL, organisation, bucketName string) StoreOption {
 }
 
 // Usage example: `storeInstance, err := store.NewConfigured(store.StoreConfig{DatabasePath: ":memory:", WorkspaceStateDirectory: "/tmp/core-state"})`
+// Use this when the workspace state directory is being assembled
+// incrementally; otherwise prefer a StoreConfig literal.
 func WithWorkspaceStateDirectory(directory string) StoreOption {
 	return func(storeConfig *StoreConfig) {
 		if storeConfig == nil {
@@ -241,6 +243,8 @@ func (storeInstance *Store) IsClosed() bool {
 }
 
 // Usage example: `storeInstance, err := store.NewConfigured(store.StoreConfig{DatabasePath: ":memory:", PurgeInterval: 20 * time.Millisecond})`
+// Use this when the purge interval is being assembled incrementally; otherwise
+// prefer a StoreConfig literal.
 func WithPurgeInterval(interval time.Duration) StoreOption {
 	return func(storeConfig *StoreConfig) {
 		if storeConfig == nil {
diff --git a/workspace.go b/workspace.go
index 0df43a3..697a8f2 100644
--- a/workspace.go
+++ b/workspace.go
@@ -113,9 +113,9 @@ func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) {
 		return nil, err
 	}
 
-	validation := core.ValidateName(name)
-	if !validation.OK {
-		return nil, core.E("store.NewWorkspace", "validate workspace name", validation.Value.(error))
+	workspaceNameValidation := core.ValidateName(name)
+	if !workspaceNameValidation.OK {
+		return nil, core.E("store.NewWorkspace", "validate workspace name", workspaceNameValidation.Value.(error))
 	}
 
 	filesystem := (&core.Fs{}).NewUnrestricted()