Bookclub tapas

Maddie Sullivan (she/her) - IRC: ElephantErgo, https://ElephantErgonomics.com, hello@ElephantErgonomics.com

Format: 32-min talk ; Q&A: BigBlueButton conference room Etherpad: https://pad.emacsconf.org/2025-bookclub-tapas
Etherpad: https://pad.emacsconf.org/2025-bookclub-tapas
Status: TO_INDEX_QA

Talk

00:00.620 Introduction
00:29.680 Hi, I'm Maddie!
01:03.840 Bookclub Tapas
02:00.520 Bookclub
02:40.300 Too many hats, too many roles
03:55.800 Narrativiation
05:24.780 My starter kit - My stock, off the shelf suggestions
05:47.660 Now what?
05:58.980 Our overarching goal
06:23.460 Our development focuses
07:05.120 The rest of the headings
08:37.980 Conversationality
10:55.480 Ad-hoc means lesricsf tion
13:01.920 Gratis documentation
14:48.440 Keeping the thread of your intention
16:21.500 Bookclub is becoming too much
17:25.240 Introducing Tapas
18:22.840 What are Tapas, what are Tapas not?
22:25.180 Tapas are maybe best illustrated by example
25:52.340 Introducing Squint
28:36.100 What else does Bookclub Tapas do?
29:08.160 Let's work together

Q&A

Description

I've been experimenting with a new programming methodology that I've stumbled upon. I call it "Bookclub Tapas". It is comprised of two parts, "Bookclub" and "Tapas". Together, they form a literate-inspired, Agile-inspired development method which centers around developer self-reflection as a means to chip away at identifying powerful custom-fit abstractions.

Bookclub turns literate programming on its head by having the target audience of the source document's commentary be its own developer. Bookclub files contain source code, issue tracking, research, feature requests, and reflections on the development process all seamlessly integrated into a single file. Developers no longer have to worry about keeping track of what they want to be doing, why they want to do something, or even the full picture of how to go about doing something, because the Bookclub file acts in cooperative conversation with the developer as a living record of their hopes, intentions, and efforts.

Tapas is the idea that instead of writing stand-alone programs, we write library ecosystems. Instead of getting ahead of ourselves by trying immediately to write large programs to solve large problems, we instead focus on writing abstractions that reduce the scale of our problem. Our goal is to identify what sort of tool would make the problem at hand trivial to solve, implement said tool, and even work recursively to implement tools to implement our tools. Our goal is that each next level of abstraction is roughly a three-line trivial case of the level of abstraction below, and eventually the solution to our initial problem is itself trivial.

Over the course of the talk, I intend to dive into what is Bookclub, what is Tapas, what do they look like when used together, and why they provide a meaningful set of methodologies both for getting real work done and also elevating the programming process' beauty. I will use a live demo centered around light development on a real-life yet-to-be-released Emacs Lisp package. I intend to showcase how Org Babel enables Bookclub by allowing for incredibly malleable documents that seamlessly integrate source code, documentation, issue tracking, research, and even the build process. I also intend to showcase how the Emacs Lisp macro system enables Tapas by allowing us to recontextualize and reinvent syntax in order to build powerful, composable abstractions that do exactly what the context calls for while using phrasing that is both natural and intuitive.

About the speaker:

Hi! I'm Maddie Sullivan, my pronouns are she/her, my handle is ElephantErgonomics (ElephantErgo on IRC), and my email is hello@ElephantErgonomics.com. My talk is on a programming methodology I've stumbled into that I've come to call "Bookclub Tapas". It's inspired by literate, agile, and last year's Emacsconf! I've had great success with it for my personal development process, and I'm hoping you can get something out of it as well. I'll be laying out what it is, how I found it, why Emacs makes an awesome environment for it, and how you can get started with it too!

Discussion / notes

• Q: I missed the beginning of the talk... did you show  examples of files in bookclub style? that seems to be related to what I've been doing, but coming from different influences...
  • https://github.com/ElephantErgonomics/Squint
  • A: So I included a... Let me see, I'm just looking at the IRC here and smiling at all the people. So, yes, I provided a link. So I think that an excellent... So I have gone ahead and provided the link to the repo and I'm going to go ahead and post that again. So this should serve as a full example of what a just sort of standard book club file looks like. And if anyone has specific questions about anything in particular, they would love to see my walkthrough and narrate specifically, you know, any place in this file that they would like to see me go over live, I would be super happy to do that. So I have the whole more or less complete book club file for Squint pulled up here. Yeah, I have my vision laid out, which has my initial sort of goal. The background and the vision sort of combined to lay out what my general sort of goal is.
• Q: The product of a Tapa like squint.org would be pure GOLD for an agent like Claude Code - have you experimented with providing an agent with the final output and letting it chew through todos?
  • A: The product of a tapa like squint.org would be pure gold for an agent like Claude Code. Have you experimented with providing an agent with a final output and letting it chew through to-dos? That would be a really excellent question. I actually just kind of recently got into Claude in particular. I played quite a bit with GPT and and a lot of 8 billion parameter local models. And I was never super impressed. It always felt like I was just sort of wrangling to get it on the same page, whether as a result of sycophantism or really just not having enough parameters in order to understand the context of what's going on. Claude has completely changed my perception of what an LLM can do or not. It makes autonomy not seem like a total fever train. I have definitely been curious about how an LLM would react to book club files. I think that, yeah, especially like, I've been daydreaming a little bit about, you know, having it generate scratch artifacts or suggesting, you know, changes to the format. It's like, yeah, the fact that this is all like, you know, like super, The goal and the hope for all of this is that we're being verbose about our thinking anyway. This is sort of how, by default, deep reasoning kind of works. 
  • I actually think that I totally agree. It would be a great fit. I have yet to personally do it, because I've always been just a little bit wary about, like, you know... Well, if I'm writing a program, I want to write it, you know? People often talk about, like, you know, oh, I just want to hand off the boring parts to Claude. But the thing is, if I'm writing in Elisp, I find the whole thing to be kind of fun. I'd be super interested in, you know, just sort of as a point of exercise, seeing what it's capable of. Because I think, I really do think that this would be kind of an ideal environment. It is kind of close to, you know, native-ish, how LLMs think. There's also, like, you know, of course, the, um, the privacy angle. I don't necessarily want to provide a whole bunch of code verbatim that I intend to GPL3. But I believe that Claude kind of has a better policy in terms of what does and does not become training data. I'll have to look into Claude in particular because I feel like that would be my target for it. But yeah, I think that's definitely onto something. I've definitely thought about this. I've definitely been really curious about this.
• Q: Do you think every Tapa should have it's own Bookclub file as well? Or would you rather keep just one bookclub file in the top of the project?
  • So I think that I definitely would advise that each Tapa have its own book club file. The reason being is because I find that for me personally, the way that my brain kind of works is that out of sight, out of mind is very literal for me. I find that... I find that... What am I thinking of? Sorry, I just saw that I got an email and I'm like, yeah, okay, cool. Case in point, right? We are at case in point, you know, out of sight, out of mind. Yes, no, absolutely. Yeah, no, exactly. I, um, I'm definitely quite ADHD and it works for my advantage because it provides all sorts of versatility. This is another great advantage of book club. If you have an ADHD mind like I do where, you know, You love jumping around and working on all sorts of different pieces simultaneously. You don't like sitting down and doing the same thing all day unless it really latches onto you. You know, you can pivot and you don't do anything. It really rewards the fact that you can pivot. So I find that to be really excellent.
  •  But to go back to the original question, I would definitely recommend, at least in my circumstance, I find it to be incredibly useful to have each tapa be its own book club file rather than to have a unified file that holds all of your tapas. You can definitely do this, especially if you're using org to organize it hierarchically. It's just sort of a matter of preference and style at that point. So long as you're making a clear distinction between your tapas, that's the main thing that I would recommend no matter what, because the whole hope that I have is that you have a sort of separation of focus between the different you know, the different focuses of your different tapas, they really should ideally feel like different programs so that you're not, you know, getting over yourself, getting ahead of yourself. 
  • I think that, you know, on that basis, I would probably default to recommending that tapas have their own separate book club files, because ideally they should kind of be different sort of independent but related thoughts. But at the same time, I mean, like, you know, this is coming from someone who like has a billion small, like, you know, I had one giant org file for a long time and then realized that really didn't work for me. So now I have a billion tiny ones. So depending upon how you feel about, you know, should I have one really big org file or a bunch of really little org files? I feel like that more or less gives your answer. I think it's whatever works best for you. I know that far and away what works best for me is having separate files. No matter what, you should have separation of concept though. But however you do that is, you know, is best your judgment call.
    • ([Sacha]: Oooh, if you're jumping around a lot, C-u org-refile is great for that, set it up with your agenda files)
  • Thank you! Makes sense!
• Q: How do you build habits when it comes to documentation? I tend to produce lots of documentation in one go, then effectively "forget" to do it for long periods of time, and end up playing catch-up which results in a loss of precision as you aluded to in your talk. In a work setting, when something goes on fire or priorities change, it can be hard to keep discipline. Would love your thoughts, thanks!
  • A: Yes, absolutely. So what I tend to do is I don't... So really, so far, what I've been doing is that I haven't been making a conscious priority of writing documentation at all. And if that sounds contradictory to the talk, that is correct. What I mean by this is that I go about is that when I'm writing code, when I'm writing, you know, drafts of my functions, the way that I tend to approach this, the way that I really emphasize the approach for it, is that I want to focus first and foremost on sort of like just writing down what my internal monologue is for what I'm doing for that pass working on the file. So my document takes ultimate... Distance of doc is ultimately a property from the fact that I am writing what I'm doing as I'm doing it. And it's more or less just I'm just mashing out the stream of consciousness of what's going on inside my head as it's happening. 
  • So if we go down and we take a look at, yeah, so let's go ahead and take a look back at the macro. Yeah, really, this is kind of cheating, because mostly I would consider this to be self-documenting, but we all kind of know that that in and of itself is a slippery slope. That's not great. Because it's like, I could believe that this would be self-documenting if this was a three-liner. It is not. which, you know, also goes to show me that this needs to be splitting into its own Tapas I intend to, you know, write a Tapa that's a sort of macro builder that automatically, you know, does the gensyms for you. Something along the lines of what's the Common Lisp macro for that called? It's like, there's some Common Lisp faculty that does automatic gensym binding. I can't quite remember what it's called. A prior version of this talk had my live coding that, but that ended up sort of distracting from what I kind of wanted to nail out and focus on. 
  • But really kind of what I do is that, let me see here if I can find some sort of... Yeah, so I have in my research section sort of layout like what the quirks of all this sort of are. I think my development focuses contain a little bit of what could be ultimately considered to be documentation. Yeah, as I'm looking through all of this, I'm kind of realizing that like, you know, yeah, there's stuff that I'm into documentation here, but it's all a little ad hoc. You know, I would, in part, the design of this particular tapa is arguably not currently, but is going to be simple enough such that a doc string is sufficient for documentation. That is not the case currently.
• Q: How do you write examples and tests? I think that you mentioned that during the talk, but I couldn't find them on a very quick look at your org file in the squint repo...
  • My use of the word test was a little bit creative. It's my validation of the code that I've written. I more or less tend to do a, I tend to try and write really small functions and have really aggressive validation by just making sure that, like, you know, when I chain functions in the REPL, each step of them produces results that are really quite immediately and self-verifiably seen. Now, this isn't a great excuse to not use a test suite, but it's gotten me pretty far. 
  • What I mean by tests is that in the research sections, what I've done is, so I've created a sort of tested in the sense that I have created a really highly representative case of the way that the program ultimately ought to behave. In doing so, I created a sort of embedded domain language that I have termed Animal Houses. And Animal Houses is a sort of markup language that has rather simple rules. This here is the entirety of the spec for Animal Houses. Grammar or anything, but like, it is more or less. Breadth of everything that needs to be known about how Animal Houses works. And I've created Animal Houses because it is an ideal and incredibly simple circumstance for how to go about as-needed tests for how Squint ultimately ought to work in practice. So when I'm doing research, what I do is I take the text of animal houses, and I will go ahead and insert it into a buffer. And I'll just create an analog buffer. I just called it awoo. 
  • And then what I'll do is in my research sections, I will write... Like I'll write like step-by-step instructions on how to go about with a REPL-driven detection using Animal Houses. So it does squint pass label to :with-restriction: correctly. The tests conducted here indicate that it does not. And then I link to a development focus that effectively acts as my bug report, or, sorry, my bug listing for this particular problem that I've identified. I lay out some criteria of how to go about using the REPL to... you know I identify what I believe is sort of like the quarantined area that I found for the bug, and then test is that I will go about engaging with narration the step-by-step of how I produce the circumstances around the bug until I ultimately narrow all the way in and arrive at a conclusion. 
  • Yeah, this is the sample text for animal houses. This is the spec, not a formal grammar, but it is more or less the whole of the spec that you need to write a parser for animal houses. Most of the tests around Squint involve writing ad-hoc parsers for animal houses. Just when I have it in its own buffer, you know, I find, more or less, it's an excellent way of going about testing in an ad-hoc sort of REPL-driven manner that I just sort of write regular... that pull out the pieces of the sections of buffer that represent the different fields and data types in association with the animals and the houses to which they belong. And then when I am engaging in research, what my research section is, is I'm ultimately just laying out, like, you know, I'm thinking to myself, is this working right? I feel like there's something here, something in this area. And I'll ask myself, well, what is it, what am I looking for? And then nail down, how am I going to go about looking for it? The process of working with the REPL to pin down what exactly is going on and come to a conclusion on... 
• Q: what is the largest project in terms of team size you had the chance to consult and introduce the Bookclub Tapas concept and what have been your experiences with these setups (implying larger applications / solutions a company is working on)?
  • A: It's been interesting. So in regards to this, the largest, I would say two people in a couple of different circumstance. So it's the pair of us working in a startup context. And then, you know, we both have like rather technical backgrounds. We can both more or less, you know, You know, sort of reason about particularly excite, especially as we've been building up top us is that, you know, well, we're both rather technical. You know, I'm definitely software engineering sort of end. And, you know, this partner is more. I mean, he's done all sorts of different engineering, but none of it in a, like, especially software context. So like, you know, but what's been really cool about that is that especially as we've built up top us and made clear distinctions about what they ought to do, you know, he doesn't have a ton of like really, he doesn't like experience like specifically in software engineering, but because we have it all laid out in this really flexible way, he's able to pick up the ball and like, you know, like he's able to take the ball and run with it. because it's all laid out in a way that's so intuitive. Like, you know, he's able to like collaborate with me and like, you know, like, you know, run off these ideas and like really go for it. Like, you know, almost as quickly as I can, just because we've set up a structure where like all of the different pieces have these really intuitive and intrinsic and straightforward roles. And that's, that's something that's really exciting in of itself that I didn't really go over in the talk. Like a managerial perspective, this is actually a really excellent way of understanding the whole context of like what the software stack looks like. Because it's like, you know, it makes it more intuitive for developers for sure, but it makes it more intuitive for everyone. You know, it's on that basis that I can't imagine clients like just a better way at this point. Um, that was that was the other circumstance where I have been working with a partner. This has been with, um, you know, I would be, uh. You know, sort of going back and forth with someone who had hired me. Um, to, uh, like, you know, to work on contract. And I would use this to sort of go over with them about, um. Sort of get a solid idea of scope and function, do pre-planning as we're going into more specifics on what the overall look for the project and how it ought to look and how it all ought to be laid out. So there's a lot of really exciting flexibility there that I think is really cool.
• Q: people will also be curious about the mechanics of collaboration: other person uses Emacs and Org? Shipping things back and forth via git / version control? CRDT?
  • A: Screensharing, I'm stepping through the buffer by hand. Using Emacs+Org is a bit to ask. I love the idea of crdt, would love to use it with someone someday. Also would be nice to have people thumb through individual Tapas in the stack.

    • Note: (ah, maybe Org publishing for ease of reference)

    • Maybe a read-only version of the Org, making screensharing a little bit neater.

• Q: Have you experimented with something like whisper.el for doing speech-to-text as you think out loud into your Bookclub? Might also be fun to hook it up to Org-capture to link to whatever you're looking at and then save it to your file
  • A: Have you experimented with whisper.el for doing speech to text as you think out loud into your book club? Now I am. I love that idea. That is awesome. Yeah, no, I love that. 
  • [Sacha]: Even with... I only have a CPU, no GPU on mine, it does capture things a lot faster. And because it actually saves the recording to a WAV, or I guess you can configure it, in case it doesn't recognize something well, you can go back and check it. That's nice. I like that more than a straight speech-text thing. I've been mulling over the idea of having a keystroke save into a background buffer so that even when I'm looking at something else, I can dictate into my equivalent of the book club file. 
  • [Maddie]: Yes, yes, yes, absolutely. So you can be scrolling through documentation on, like, you can be scrolling through documentation on one screen and you can be musing to yourself about, like, you know, is this supposed to work this way? Like, you know, like, what in terms of, like, you know, like, I see this function. It sounds like it's what I'm looking for. I don't know if the types are quite right. I don't understand. It's named what I'm looking for, but I don't know what it's taking in. You can reason through all of this. You're not even writing into the buffer that you're working with. That's actually so cool. 
  • [Sacha]: Or you can tie it into the org capture process so that it can pick up an annotation automatically. Sorry, annotation is the link to the thing, whatever you're looking at. 
  • [Maddie]: Oh, that's super cool. Yes. No, I actually really love it. I haven't, you know, hooking this all up to Org Capture at all. I actually really love that idea in and of itself. Yeah. 
  • [Sacha]: Org capture will give you a lot of capture options. You can capture to your currently clocked in heading. So then it just files your note in the right place automatically. 
  • [Maddie]: Absolutely. I love that. Let me see. I'm actually like writing a note to try that out. I'm definitely going to have to do that. Like the flexibility of that in particular sounds just perfect.
    • Also related: https://newsletter.pragmaticengineer.com/p/san-francisco-is-back?open=false#%C2%A7wispr-flow-a-new-modality-for-programming

• Q: I guess a major pro is it has less friction as people can do (a lot, maybe not everything) in BookClub Tapas file vs. having to log into gazillions of different systems, each one of them keeping a portion of the information. Did I get that viewing point right from your elaboration of the collaboration between you and your team mate(s)?

  • A:

• i appreciate how easy this is to follow

• i think i'm already getting an idea of how this comes together
• Important caveot on this callout: The Emacs community has been really great about this, but this is a pain point of software development as a whole 😛
• I don't think I've ever written really excellent documentation...
• i don't think i've ever written even decent documentation
• I don't know if I have ever written excellent documentation but I do actually enjoy writing it. But partly because I do tend to approach projects the way you are describing in this talk! And I like having a name for this process!
  • one of my ways of writing a mix of tests, examples and documentation is here: https://anggtwu.net/eepitch.html#test-blocks
• modern world, no time to read or write it anymore
• A: I'm so glad to see that people are noticing bits and pieces of already doing all of this! 😊 I definitely found a lot of what I arrived at out in things that we're already doing. My hope was to formalize, name, and pull it all together 😊
• “Clean Code" from Robert C. Martin ("Uncle Bob") is also worth taking a look and his views on documentation and so on.
  • A: Clean Code is definitely a big inspiration for me, and I would highly recommend just about anyone read it. I don't think all of it is perfect, but all of it is worth considering
• i definitely think this has a good balance between complexity and simplicity
• Thank you! 👏
• Great talk!
• Excellent work!
• great talk
• Interesting concept! Now I'm thinking about how can I adopt it
• I definitely noticed the utility of this process for ADHD
• Would be very cool to record buffer information to effectively bookmark the context for that stream of thought
• https:////newsletter.pragmaticengineer.com/i/177384640/wispr-flow-a-new-modality-for-programming "In the office, every desk is fitted with a $70 BOYA Gooseneck microphone, into which devs whisper"

Captioner: sachac

Questions or comments? Please e-mail hello@ElephantErgonomics.com