From 14517ee91fc29751fc791e80d613c5130eb2fa3d Mon Sep 17 00:00:00 2001
From: Lyndsy Simon <lyndsy@lyndsysimon.com>
Date: Thu, 11 Oct 2018 22:57:16 -0500
Subject: [PATCH] Expand README

---
 README.rst | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/README.rst b/README.rst
index 1db4301..170eb71 100644
--- a/README.rst
+++ b/README.rst
@@ -28,13 +28,46 @@ structured reports based on a model:
         def email(self, row):
             return row.email
 
+Once a report is defined, executing it and sending it multiple places at once is
+easy:
+
+.. code-block:: python
+
+    from columnist import transform, destination
+
+    report = RegisteredUsersReport()
+    # Save the CSV to disk
+    report.add_output(
+        transform.CSV,
+        destination.File('/var/log/reports/users.csv'),
+    )
+    # Send encrypted CSV as an email attachment
+    report.add_output(
+        transform.CSV,
+        transform.GPG(recipient='...'),
+        destination.Email('lyndsy@lyndsysimon.com'),
+    )
+    report.output()
+
+Note that ``add_output()`` defines a workflow, but *does not perform it*.
+``.output()`` must be called before the report is generated. This is due to the
+fact that Columnist is designed to iterate over the source query *once and only
+once*. Transformations are applied one row at a time, and that row is sent to
+each destination in turn before the next row is transformed. This allows large
+reports to be streamed to multiple destinations simultaneously, potentially even
+in multiple formats?
+
+Have a query that takes ten minutes to run, and need it to output it to disk,
+encrypt it with GPG and send it to an SFTP server, and store a backup on S3
+after running it through SOPS? No problem!
+
 Project Roadmap
 ---------------
 
 ``columnist`` is currently incomplete, but under active development. Upcoming
 features include:
 
-- [ ] Explicit column ordering in output, other than the order in which the
+- [x] Explicit column ordering in output, other than the order in which the
   are defined
 - [ ] Simpler definition of columns that are simply untransformed row attributes
 - [ ] Aggregation based on a time series
@@ -44,7 +77,7 @@ features include:
 
 - [ ] Report generation in multiple formats
 
-  - [ ] CSV
+  - [x] CSV
   - [ ] JSON
   - [ ] XML
   - [ ] Plugin architecture for arbitrary output
-- 
2.45.2