diff options
Diffstat (limited to '2025/talks/bookclub-tapas.md')
| -rw-r--r-- | 2025/talks/bookclub-tapas.md | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/2025/talks/bookclub-tapas.md b/2025/talks/bookclub-tapas.md index 5d0574b1..3f8f877c 100644 --- a/2025/talks/bookclub-tapas.md +++ b/2025/talks/bookclub-tapas.md @@ -64,6 +64,358 @@ 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"]] |