How I Streamline Small Group Discussion Guides

Posted on

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 called snot (for (S)ermon (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 snot.


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.

Automatic References

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