diff --git a/services/workflow/README.md b/services/workflow/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..260ee6bb3d8e6303d603c9e6992e9eb0aad7c3ca
--- /dev/null
+++ b/services/workflow/README.md
@@ -0,0 +1,16 @@
+# Workflow: the Workspaces Workflow Service
+
+To use, first run the Alembic migrations:
+
+    env CAPO_PROFILE=local alembic upgrade head
+
+Then you should be able to run this with:
+
+    env CAPO_PROFILE=local pserve --reload development.ini
+
+Once there, try the following URLs:
+
+- http://0.0.0.0:3456/workflows
+- http://0.0.0.0:3456/workflows/0
+- http://0.0.0.0:3456/workflows/0/files
+- http://0.0.0.0:3456/workflows/0/files/file.txt
diff --git a/services/workflow/README.txt b/services/workflow/README.txt
deleted file mode 100644
index 97c634472eac4749d2358fc8b07c3a04e0135f75..0000000000000000000000000000000000000000
--- a/services/workflow/README.txt
+++ /dev/null
@@ -1 +0,0 @@
-# Workflow: the Workspaces Workflow Service