path: root/2025/talks/bookclub-tapas.md

[[!meta title="Bookclub tapas"]]
[[!meta copyright="Copyright © 2025 Maddie Sullivan"]]
[[!inline pages="internal(2025/info/bookclub-tapas-nav)" raw="yes"]]

<!-- Initially generated with emacsconf-publish-talk-page and then left alone for manual editing -->
<!-- You can manually edit this file to update the abstract, add links, etc. --->


# Bookclub tapas
Maddie Sullivan (she/her) - IRC: ElephantErgo, <https://ElephantErgonomics.com>, <mailto:hello@ElephantErgonomics.com>

[[!inline pages="internal(2025/info/bookclub-tapas-before)" raw="yes"]]

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](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](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"


[[!inline pages="internal(2025/info/bookclub-tapas-after)" raw="yes"]]

[[!inline pages="internal(2025/info/bookclub-tapas-nav)" raw="yes"]]