I don’t like repetitive work: it sucks the joy out of otherwise fun tasks. So when I started creating discussion guides for our small groups (we call them Community Groups, or CGs), I set out to eliminate as much of the tedium as possible by applying technology I also use at work. Here’s a little glimpse.
My workflow includes several components: a text editor, a couple of apps that automate boring stuff, open source software, and a pipeline to execute it all.
The centerpiece of my work is my text editor. I use Neovim, a modal editor based on Vim (which itself is based on vi). Modal means you can’t just type; you start out in normal mode. Modes throw new users for a loop, to the point that even figuring out how to exit the editor can be difficult for the uninitiated. To type, you enter insert mode. There are also various visual modes. All this allows a user to navigate and edit text very quickly. Plugins provide endless customization. I write all the discussion guides in Markdown, a plain-text way to add things like headings, lists, tables, links, etc. The screenshot above actually shows one of my guides.
Pandoc & Snot
How do I get the Markdown guide into something I can send to the CG leaders? Pandoc. Pandoc is the Swiss-Army knife of converting documents into other formats, like Markdown to PDF. A simple command puts my text-only guide into a Latex template and generates a PDF. You can see part of the template below. The most interesting thing is that Pandoc takes the “front matter” in my Markdown—title, passage, date, etc—and puts it into the right spot in the PDF, so I just create the content, and Pandoc + Latex take care of the formatting.
For some, this would be automation enough. Not me. So I wrote a small Go app
snot (for (
NOT)es; I am better at building things than
naming them). It automatically generates a skeleton guide for the coming Sunday
with series info, speaker, and structure already filled in. It also
continuously rebuilds a PDF as I am editing the guide. And it takes care of
composing an email to all the CG leaders with the guide PDF attached. All these
things are done with different commands inside
So far so good, but we’re not quite there yet. As with all code, I keep it
under version control (using
git). All changes are tracked and every guide
“released” with a tag. That means I can go back to any guide and re-create it
at will. Since these guides are done very linearly, I won’t need to use any of
the more advanced revision control features, and that’s okay. But it allows me
to pull everything together in a hands-off and repeatable way using
Drone as a pipeline runner. I host it in a Docker
container running on a server in my closet.
Pipelines like these connect to the revision control repository and often take
care of continuously integrating code and deploying it into production. Mine
runs whenever I add a tag to a specific discussion guide revision. The output
looks like the screenshot below. It checks out the code (i.e. discussion guide
text) at that tag, runs
snot build to build the PDF, and
snot email to
email that PDF to the leaders. The whole thing runs on my server, not my
laptop, so I don’t have to watch it or wait for it.
With pipelines set up and back on my laptop, when I am done creating the guide
and email, I just have to type
snot publish. That does a few checks, tags the
current version, and pushes it to the repository, which triggers the pipeline,
resulting (after about 1 minute) in an emailed discussion guide.
The final product (sans email) looks like the screenshot below. Not bad for only writing some plain text and running a few commands.
One handy feature would be a list of all the Scripture references from the sermon, including the main passage. That’s what I find myself making note of most frequently. I recently came across a REST API for the ESV that is free for this kind of use and decided to write another little app (this time in Rust) that searches the sermon manuscript for anything that is formatted like a reference, looks up the passage using the ESV API, and prints it out as a table. You can see the result below.
What I actually do
With so much of the process automated, what do I actually do each week? I spend about an hour working on the guide. Once I get the outline, I fill in as much as I can, look at the passage, and try to come up with discussion questions without knowing the focus of the sermon. Sometimes I am off, but it gives me a head start. On Sunday morning I get the sermon manuscript, read through it, and add more questions. I bring my laptop to church to take more notes. After the service, with everything already in good shape, I do some final edits and usually have the guide out before noon.
Photo by Aaron Burden on Unsplash