Improved documentation

README.md

@@ -1,6 +1,40 @@
-# League of Women Voters of West Virginia
+# League of Women Voters Member Management Tools
 
-Custom-developed software designed for the League of Women Voters of West Virginia, as well as any state or local League affiliated with the League of Women Voters.
+Custom-developed software for the League of Women Voters of West Virginia (LWVWV) and other LWV state/local leagues. This toolkit automates the workflow from portal membership exports to Mailman 3 list subscriptions, with optional legislative district lookups.
+
+## What This Project Does
+
+Managing membership across multiple mailing lists and tracking legislative districts is time-consuming. This software automates:
+
+1. **Data Retrieval** - Download member rosters from the LWV portal
+2. **Data Processing** - Convert CSV formats and query Google Civic API for district info
+3. **List Management** - Subscribe members to appropriate Mailman 3 lists
+
+## Three Ways to Use This Software
+
+### Standalone Scripts (Manual)
+- Download rosters: `download-roster.js`
+- Process/district lookup: `google-civic-api.pl`
+- Subscribe one list: `subscribe-members.sh`
+
+### Full Automation (Docker + Ofelia)
+- Complete hands-off operation
+- Scheduled roster downloads
+- Multi-list subscription with league filtering
+- Error notifications via email
+
+### Hybrid Approach
+- Use standalone scripts for one-off tasks
+- Use Docker automation for recurring operations
+
+## For Other LWV Leagues
+
+While originally developed for LWVWV, this software can be adapted by any LWV state or local league. The main adaptations needed are:
+- Update `$STATE`, `$stateLeagueID`, and `$localLeagueIDs` in `env`
+- Configure your LWV portal `$MEMBERSHIP_URL`
+- Set up your Mailman lists and `$MAILMAN_LIST_ID`
+
+See [Configuration](#required-file) for details.
 
 ## IMPORTANT: Format for roster