We are sponsored by audible! http://www.audibletrial.com/programmingthrowdown
We are on Patreon! https://www.patreon.com/programmingthrowdownT-Shirts! http://www.cafepress.com/programmingthrowdown/13590693
Join us on Discord! https://discord.gg/r4V2zpC
Code Documentation with Omer Rosenbaum and Tim Post
What makes for good documentation? In this episode, we dive into one of the most important yet overlooked facets of coding. With us are Omer Rosenbaum and Tim Post of Swimm.io. Swimm is an app that allows you to create docs coupled with your code, which are auto-synced and integrated into your workflow. It makes for much more efficient, elegant, and accessible documentation.
Omer is the CTO of Swimm, and Tim is Principal Development Relations and User Advocate. They are the experts who will guide us through good code documentation practices and tools, as well as share some fascinating real-life examples and stories.
This episode touches on the following key topics and ideas:
00:01:20 Introducing Omer and Tim
00:03:28 Omer: learning tech while in the military
00:06:36 Israel Tech Challenge
00:08:32 Impostor Syndrome
00:12:15 Tim: the consulting career route
00:18:15 Stack Overflow elected moderator
00:20:59 ZFS and Btrfs
00:22:49 What is good code documentation?
00:34:48 Documentation and remote work
00:36:99 Good practices
00:40:37 Code comments
00:45:20 How to write documentation
00:46:59 Signs of bad code documentation
00:48:05 Swimm overview
00:53:21 PyTorch documentation
00:54:45 PHP documentation
00:56:34 Swimm’s CLI tools
01:01:16 Code documentation horror stories
01:07:26 Swimm offers for open-source projects and enterprises
01:13:47 Working at Swimm
01:19:54 The value of remote work
Resources mentioned in this episode:
Tools
Swimm https://swimm.io/
Electron https://www.electronjs.org/
Stack Overflow https://stackoverflow.com/
Catch Swimm on:
If you’ve enjoyed this podcast, you can listen to more programming news and updates like this one on Programming Throwdown’s website: https://www.programmingthrowdown.com/, or send us an email at programmingthrowdown@gmail.com.
You can also follow Programming Throwdown on
Facebook | Apple Podcasts | Spotify | Player.FM
You can also help support Programming Throwdown through our Patreon.
Transcript:
Patrick Wheeler: Programming Throwdown Episode 114, Code Documentation with Omer Rosenbaum and Tim Post. Take it away, Jason.
[00:00:24] Jason Gauci: Hey everybody. This is a, an awesome show. I think code documentation is extremely, extremely important. It gets more important as you move along in your career. So if you're just starting out, it could kind of catch you by surprise.
[00:00:40] It might seem like if you're just programming a high school project that you're turning in the next day, you might not realize like how incredibly, incredibly important it is, but I can tell you as somebody who's been programming for a long time, I go back and look at code that I've written, let's say five years ago, and I have a bunch of documentation and it feels actually really good. It's easy to jump into it. And when I look at code that I wrote, when I was a more junior engineer, I've no idea what's going on. And it's a total rewrite.
[00:01:06] So I can tell you firsthand is extremely important. And it's also very difficult to do kind of efficiently and to make it kind of party or a team. So it's a great topic to really dive deep into and spend a lot of time talking about.
[00:01:20] And we're here with Omer Rosenbaum and Tim Post. Omer is the CTO of Swimm, which is a company that really focuses on the documentation ecosystem. And Tim is the Principal Dev Rel and User Advocate for Swimm. So thank you both for coming on the show. I really appreciate it.
[00:01:36] Tim Post: It's great to be here.
[00:01:38] Omer Rosenbaum: Thank you for having us.
[00:01:39] Jason Gauci: Cool. So before we jump into it, let's talk a little bit about your backgrounds. So what is kind of your journey that led you to either found or come to Swimm and, and what's that, that story like. Maybe Omer, you could go first, and then Tim, I'd love to hear your story as well.
[00:02:00] Omer Rosenbaum: Yeah, sure. So my name is Omer, I'm based in Israel and basically the first time I got a really amazing training experience was in the Israeli military. As Israelis, we go through the military, it's obligatory here, and I had a really amazing experience learning a lot in a very short period of time, how to program and many other things.
[00:02:25] And I got actually fascinated by how efficient teaching and learning can be. And how much of an impact it could have. And I also get to teach a lot and train people in various places. One of them in a program called Israel Tech Challenge. And I also get to lead a Security Academy by Check Point, and to train a lot of people in many places.
[00:02:51] And then I got to see them many times when they succeed, and also when they struggle, when they get into new positions. And they always shared with me the experience of onboarding, at first, to their new jobs and being thrown into the deep end of the pool, people telling them, okay, you need to get going really fast, learn a lot really fast.
[00:03:14] And ever since then, I always had that in mind that someone needs to tackle that pain of people trying to get familiar with code bases really fast and really efficiently.
[00:03:28] Jason Gauci: Yeah. So just to unpack that a little bit. I have a friend who's from South Korea and they also have, I believe it's a year or two years of military service.
[00:03:37] And, I guess as someone who, I grew up over here, we're, we're in the US, where we don't have that, I always thought that that was kind of like, they teach you how to hold a weapon and they teach you, and you kind of walk a post and you peel potatoes, or like, just stuff like that.
[00:03:52] But it's actually really interesting to hear that, as part of this service, you could do a lot of really cool tech stuff. And so, yeah. Can you dive into that a little bit? Cause that's something I think is really fascinating,
[00:04:04] Omer Rosenbaum: Right. I think, well, military is big and there are many different positions there.
[00:04:10] I was very lucky to have a meaningful technological service, I feel. And I think one of the very special things there is that, the military takes people who are 18 years old, very young, without much of experience. I mean, how much experience can you get when you're 18, and they need to train you very fast and effectively.
[00:04:30] So after three and four months, you are already productive and creating a lot of value, even if you haven't had a lot of experience beforehand. So that is one thing that I think is very special also in the army, because they get a lot of new people all the time and people get out of the army very frequently.
[00:04:49] So there is a lot of knowledge sharing and new people coming in and going out all the time.
[00:04:55] Jason Gauci: Cool. So in Israel, is it also a year? I know for South Korea it's a year, but what is the length for Israel?
[00:05:01] Omer Rosenbaum: So it's three years obligatory for men, and two years for women, at least it used to be. So, and for most people doing technological surveys, it gets longer to even five, six or more years.
[00:05:14] Jason Gauci: Ah, okay, okay. So that is definitely more time, but yeah, you're right. Me for, let's say three years or even two years, if someone takes a year to ramp up, then you've lost half of the utility you can get from that person's service. So yeah, I take it, see, that's an environment where ramping up and a good documentation is really, really important.
[00:05:32] Omer Rosenbaum: That's right.
[00:05:33] Jason Gauci: Cool. And so from that, did you, what kind of took you into the sort of private sector?
[00:05:39] Omer Rosenbaum: So actually it was a bit gradual for me and I get to go to university after the military service, as happens quite frequently, also in Israel. And I got to into many training programs because I really like teaching even when I started in the army.
[00:05:54] So I was a commander of the same course that I was a student in. So I got to teach in many different programs, and I got to mix hands-on experience with teaching and training experience in various places. So at first it was a bit scattered. So I taught in various programs before I started to, I decided to focus and found my own initiative, trying to really tackle the domain of documentation in general.
[00:06:21] Jason Gauci: Cool. That makes sense. And so you're kind of learning. And so was it more of like, when you say gradual, were you doing kind of some part-time kind of consulting? Or what happened that took you from the military into Swimm? Do you just jump into founding a company? Like how did that work?
[00:06:36] Omer Rosenbaum: Okay. So at first I was doing part-time in many training programs and one of them was called Israel Tech Challenge.
[00:06:44] It's also where I met the other three co-founders of Swimm, which is an initiative that took a lot of people who have experience from other countries than Israel, mostly. And we taught them a lot of data science and computer science stuff, but also cybersecurity. And we help them come to Israel and get incorporated with the industry in Israel.
[00:07:09] So my part there was to start the cybersecurity track and train a lot of people there. And I did that in other places as well, but specifically in Israel Tech Challenge, Every person who went through those programs went and started a new job at one of the companies here in Israel.
[00:07:27] And then I got to see in person how many really talented people with a lot of experience who start a new job, always get to feel the same challenges of starting a new position with a lot of existing code, and how hard that was.
[00:07:47] And they always talked to me at first about the difference from the experience of a training program. Like we held an Israel Tech Challenge where everything was organized and we hand-held them and helped them understand and learn a lot of things in a very short period of time. And then they were just asked to start and work on tasks without a lot of guidance. And I kind of felt that challenge through them a lot.
[00:08:13] And then together with the other co-founders of Swimm, we all worked at ITC together. I also worked with other places, but they worked at ITC most of the time. So we all got to feel that challenge and we all get to feel that this is something we want to tackle together at some point.
[00:08:32] Jason Gauci: Yeah, that totally makes sense. We have this saying where I work, it's a very common called Imposter Syndrome. And it's the idea that, you train, you train, you, train, you, take the interview. Interview asks you these really atomic questions, like, invert a binary tree or solve this dynamic programming problem. And you're on a whiteboard with very little resources, but it's such a narrow scope that with the right training, you can really nail the interview.
[00:09:01] And then all of a sudden it's like, okay, here's our, 300 million line code base, for our entire company. And here's this task that's going to take six months.
[00:09:12] And so that sort of like really an agoraphobic kind of experience, it just jars people and makes them think, well maybe I really don't belong here. I mean, maybe, this is like, I'm just totally out of my league and I may be fired. And so we call this, we call this Imposter Syndrome and everyone goes through it.
[00:09:30] And I think a lot of the reason why that exists, at least to the degree that it does is, is because the onboardin just leaves a lot to be desired. And so I think even your big companies have a hard time with that, and have a hard time with documentation in general. And we should talk later on about how those two are kind of intertwined.
[00:09:51] But yeah, that's, that's an amazing story. Yeah. We're definitely, I'd love to dive into, into some of this stuff, but first I want to hear Tim. I want to hear you talk about kind of, what kind of experiences led you to Dev Rel and, and, and then to Swimm.
[00:10:06] Tim Post: Hi, I'm Tim. I started out as a, more of a systems programmer.
[00:10:11] My first language was BASIC and then I quickly went to C and later C++, and I really cut my teeth in it, on the backend of the kernels file systems, things like that interested me immensely. So I started doing a lot of that before we really had the web, sort of as we know it, I'm kind of showing my age here a little bit. (laugh)
[00:10:35] Yeah. Back then, I mean, Netscape was, the newest and hottest thing, and we all had those GeoCities profiles with the animated "under construction" gif and all that stuff.
[00:10:45] Jason Gauci: Yeah. I remember when Microsoft made Internet Explorer part of Windows and I thought, oh, Netscape is in, is in huge trouble, but, but Netscape was a much better product.
[00:10:55] And then there was the whole anti-trust. I mean, it was a very dramatic time.
[00:10:58] Tim Post: It still is. We're still, we're still, we're just now seeing the, the, the resolution of bytes that we picked, you know, 25 years ago, but the end result is we're all getting along, which is great. But I quickly worked my way into, at the time there was a need for people that understood the Unix philosophy, I had been working with GNU and Linux since they started booting together, and understood how to configure web servers and how to manage these systems.
[00:11:28] So I started gravitating toward the web hosting industry very quickly, because there were tons of consulting opportunities for me there. And I started working on things like clusters. Single system image clusters where, instead of having two or three servers going kaput all the time, you could use the resources of all of them.
[00:11:48] And through that endeavor and many consulting opportunities, I became known in the industry as someone that could pull projects that were very late, very over budget, essentially death marches back into the black, back into the actually shipping something.
[00:12:03] Jason Gauci: Wow. Interesting. So what made you go the consulting route instead of the, sort of a, I guess, I don't know what the other word would be like, the joining the Microsoft route, whatever you would call that.
[00:12:15] Tim Post: I was fortunate in that, when I was in college, in my first couple of years in college, I had a skill set that not many people had.
[00:12:23] I understood what Linux was. I knew what GNU was. I had access to BITNET at college so that I could download stuff without paying enormous long distance phone bills using a modem. At the time it was 2400 baud. I mean, that was the fastest you were going to get. So, so I had a lot of things go right for me to give me access to things that many people didn't have.
[00:12:43] And the industry came to me. I didn't go to it. I got hired, approached essentially out of school. And I went right to work during the first .com boom. That really changed me because I never went to the route where I had to go looking for a job that early on. There was just always something else coming up, someone else that was calling me and wanted me to work on something for them.
[00:13:06] And that just eventually, like a big ball of rubber bands turned into a career. And it just sort of happened that way. So a lot of luck. A lot of fortune, some misfortune too. There's some really shady characters in the web hosting industry even today. So, but a lot of it was really positive.
[00:13:21] Unfortunately, due to the type of projects I was working on and the state that they were in, it was always a very high-stress sort of working environment for me, because you're inheriting something it's already late. You're not quite sure what it does. Well, you're not even quite sure what it's supposed to do. The scope is way far from the original. And you've got a few months where you have to pull it all back together.
[00:13:44] Jason Gauci: I was, I saw an article from the CTO or maybe as a CEO of Waze. And he was talking about when they were acquired by Google. And, and one of the things that really surprised him was that, Waze he would just fire people because of the environment. So maybe he needed like 10 lawyers and now he only needs eight lawyers. And so he would just fire two lawyers, and it kind of made sense.
[00:14:07] But in big companies, you don't really do that. Like people find a new thing to do at that big company, if they're good. And so that was one of the things that surprised him.
[00:14:16] And so, so I think, yeah, that might be one of the big differences between doing consulting and joining one of these companies is that consulting, you are just contributing all the time, which is a double-edged sword, but you always kind of have to be productive. At least that's kind of the way I see it from someone who's older, who's never done consulting. That's kind of my thousand foot view of it.
[00:14:38] Tim Post: It is, it's weird in that, well, in it, it depends on where you are in the world too, because the term "consultant" has some legal ramifications too, as far as your security, your job security.
[00:14:50] In America, we have at will employment, and I think almost every state, if not every state, I'm not sure what, what the state of that is, no pun intended. (laugh)
[00:14:58] So essentially we are consultants with benefits because our status can be, can be terminated at any time, unless you have some sort of tenure. That has beneficial both to the organization and potentially to the consultant, depending on what you want to do.
[00:15:13] You see a lot of people in consulting do this because they want to ramp up their skillset. They want to ramp up their resume. They want to ramp up. As we know, when we go into interviews, what people really want to talk about is what have you shipped before, but can you point to that? You've done. So you want to get all that under your belt. If you go, and you sort of court the big companies, you tend to move around a lot on your resume.
[00:15:33] So you might spend a year here and then get the position above you in another company, and spend two years there and then get another position above you, and spend three years there before you're up to the point where you have the compensation roughly that you want, and you're working on what you need to do.
[00:15:48] Consulting, you can take a much more direct route toward that, which I found to be very beneficial. And you also have the ability to turn work down, which is also extremely beneficial. There are some projects which are just way too late or involve a technology you just don't want to work with. And yeah, I mean, if you, if you could say no to VB.net throughout your whole career retroactively, I'm sure a lot of people could do that. You know, not nothing, they're not going to vb.net, but I know a lot of people struggle with that. So it does produce an interesting dynamic.
[00:16:19] One of the things that you notice foremost is how much time you spend ramping up in, not just ramping up, but just sort of owning the breadth of everything that you're walking into when you walk into something like that.
[00:16:34] And it, it takes months. And these are productive months, but not visibly productive because you have nothing to, to show for it. You haven't produced anything yet. And companies often don't see the value in it, and they will start saying, well, you've, you've been consulting with us for a month then. You haven't produced anything, and I'd be like, well that's because your documentation is terrible. And I still don't know what anything does.
[00:17:00] And they said, you're supposed to be able to work around that. I said, and I, I am by producing the documentation that I need in order to understand your code base. And that is always sort of fallen on begrudgingly, I would say, as you go around and do it, and it got to the point where I've even had gigs where developers actually deleted the copy on the server and kept it as ransom to ensure they got their last paychecks.
[00:17:26] Jason Gauci: Oh, geez.
[00:17:27] Tim Post: Yeah, you can really-- and it's like, if you guys don't have this documentation, you're, you're not going to be able to do anything. And I know that and therefore I'm gonna, make sure that you part amicably.
[00:17:37] So I've been in a lot of situations. It got to the point where I didn't want to approach anything else that wasn't really documented. And I became more interested in the dynamics of software development itself rather than really the code that I was working on.
[00:17:56] It was at the point where, virtualization had come along, we had new processors, Intel VT technology that could, pair of virtualization wasn't needed anymore. You could just run anything you want it to on essentially anything else. And all those years of death marches that just, I want it to take a break from it.
[00:18:15] So, at the time I was an elected moderator on Stack Overflow. This was back in 2012 or so. And I had been spending a considerable amount of time on stack overflow, answering questions, and basically just sweeping up after people.
[00:18:30] Jason Gauci: So can you tell everyone what an elected moderator is?
[00:18:33] Tim Post: An elected moderator later on Stack Overflow is a moderator that the community elects through a democratic election where a single transferable vote is used. I believe they use meek STV. And the community comes and thousands of people vote on who they want the moderators to be.
[00:18:49] And if you're lucky enough to get a slot, then, then you're appointed. And you're given essentially the same level of access that an employee of the company is
[00:18:57] Jason Gauci: Interesting. Cool.
[00:18:58] Tim Post: And then you're entrusted to be an emissary and moderator of the site.
[00:19:03] And as I was moderating, I grew more and more into why is this so addicting and why our program is flocking to this so much?
[00:19:11] So I really, really, really got into grokking developers as much as I did development and that really changed the way that I was approaching my day job. Eventually I just got so tired of it and Stack Overflow approached me and they said, we've got, we've got this opening on, on our community team. Why don't you come to work for us?
[00:19:30] And I did that and I became their Director of Community Strategy for a number of years, over almost eight years. And that was really my jump into Dev Rel. And through that, I learned a huge amount and I also started missing writing code again. So now that I've kind of come full circle with that a little bit, I'm, I'm picking up the IDE and my editor a little bit more than usual, and also contributing to the engineering side of the organization. So that's sort of the happy space where we need to be.
[00:20:01] And I'm in a position where I'm, I'm in a great place to fill immediate short-term needs of clients that the product hasn't yet been able to accomplish yet. So that, that's something that I really enjoy doing, but that that's in a nutshell, how I got into Dev Rel and also hyper fixated on documentation.
[00:20:20] Jason Gauci: Are you still into file systems like falling the whole reser, ReiserFS , and ZFS going into the kernel. And are you still on top of all of that stuff?
[00:20:28] Tim Post: Not as much as I used to be. The last one that I worked on was extended 3 Cal, which was a fork of ext3, which basically implemented copy on right. So you could basically turn ext3 into a git-repo and, roll back files from snapshots in the past, or whatever you want it to do. And then after that, I started working on some cluster file systems, but I haven't been up to speed.
[00:20:52] I remember what happened with ReiserFS, that was just tragic. I did not know about ZFS going into the kernel. That's something I need to check out.
[00:20:59] Jason Gauci: Yeah. Actually in there, there is a, like a Btrfs, or BRTFS, something like that, that one there they're both of them ZFS and Btrfs have copy on right.
[00:21:09] And so what that does for people, just like, really quick sidetrack, like, imagine if you had, let's say a cron job, that every day took your programming folder and copied it to some new folder somewhere that had, let's say today's date on it.
[00:21:23] So every day it made a May 11th, May 12th, May 13th folder. Well, so you'd end up with all this redundant data. And so what ZFS is clever enough to do is, when, if you were to let's say, copy a folder, it doesn't actually copy it. It just creates another reference. So on your actual hard drive there's still only one copy.
[00:21:41] And then, and then if you modify either one of those references, then it's smart enough to actually, you know, create a copy so that you're not modifying both of them, but it's all done kind of transparently. And so you can do things like snapshot like really efficiently.
[00:21:56] Tim Post: Yeah. They're hugely efficient. That was one of the things that, when I first saw that coming out and it was a research project, I believe it came out of the Hopkins storage lab. I think Dr. Zachary Peterson was the one that employed.
[00:22:07] Jason Gauci: Oh, interesting. I didn't know that.
[00:22:08] Tim Post: I'm working in web hosting and we have all of these, this whole farm of Pentium 4 HTs on racks, hosting websites, and backups were a huge problem for our clients. So naturally if you could do that at the file system level and make immutable copies of stuff so that you could restore it that easily, that was a huge, I wanted to hopefully build an offering around that.
[00:22:30] So that was, that was just sort of an example of some of the stuff that I worked on sort of as the whole web development culture grew up around me. And yeah, so that was basically it as far as how I really, you know, embraced Dev Rel is not so much just purely one of the other, I'm sort of both.
[00:22:49] Jason Gauci: Yeah, that makes sense. So maybe, it'd be good to really start at the beginning. We have folks who are in high school, actually, even younger. We have a lot of folks in the audience who are just getting started that, I mean, and actually independent of age, there's folks who are switching careers.
[00:23:03] And so for someone who's just getting into it, what is code documentation, like maybe what is good code documentation and why should people do it?
[00:23:14] Tim Post: Good code documentation is whatever, as you said, early, early, early on, whatever helps you learn without triggering the minimum reactions that your body has to stress is the best.
[00:23:30] So good code documentation should make you feel supported. It should make you feel as if you've accomplished something as you go through it. It should be reinforcing. It should be relatively new and complete. Should be up to date. It should be discoverable. There's a whole lot, but in order for it to be any of those things, it first has to exist, and quite often it just doesn't.
[00:23:53] People learn differently. At any given point, if you hire 10 developers, people come to you and they're onboarding, and they're, they're really vulnerable at that stage. They, they're into something new, they're, they're learning new code, new technologies, new things. They're into a new social dynamic. They're making new friends and establishing new peers, the office. They take new ways to go to work that morning. They take new ways to go home. Everything about your onboarding experience, affects people a little bit more profoundly than I think a lot of people relate to commonly.
[00:24:28] And your documentation should always be there to essentially support them in anything that they need to be able to do, from early on, to reference things. And the documentation, good documentation should also be deliberate in conveying knowledge. There's a sphere of knowledge in programming that you pick up just from being around stuff, just from being around the code, and being around the people that write the code, and being around the people that test the code.
[00:24:55] And this isn't often deliberately conveyed. It just sort of soaks in as you get through the onboarding experience. And I often challenge people to identify that tacit knowledge and make it very, very deliberate and identify what people are learning.
[00:25:11] So another big part of great documentation is listening to find out where the documentation failed. If you are a new developer and you are trying to find a piece of information and you can't find that, you need to capture that friction and give it back to whoever's maintaining the documentation or create it yourself, if you need to. And it needs to be set out very early on that that's sort of how the organization is going to evolve.
[00:25:36] ,And additionally documentation gets a really bad connotation because people are thinking, yeah, that's a thing that I have to completely rewrite from scratch every three months when it goes out of date again. And so for documentation to be good, there must be something pushing it along. It really needs to be continuous.
[00:25:55] It has to be something that, if it falls out of date, there's some way that you find out about that, and some issue is created so that people bring it back up sort of into the speed. And Omer probably has a whole lot more to say about that.
[00:26:10] Omer Rosenbaum: Sure, I think, first good documentation helps you understand what's important in that case. You mentioned when someone is new or coming to a new place, then basically first you have a lot to grasp in a short amount of time. So good documentation helps you understand what's important to focus on.
[00:26:28] And also it helps you understand the main flows going on and things that are pretty much hard to understand by just starting to read perhaps the code itself.
[00:26:38] And also it helps you understand the process to lead that the current state of the code. Because even if you read the entire code base, it would take time to, it only gives you the sense of what currently exists in the code and not what led to it, for example, the motivation or the decisions that developers have made throughout the time.
[00:26:57] So basically good documentation helps you get really fast into understanding everything you need to know in order to make meaningful contribution.
[00:27:06] Jason Gauci: Yeah. That makes sense. I think a lot of what you said really resonates with me. Yeah. I think the whole idea of it being kind of a living, self-healing system is, is really underrated, really important.
[00:27:19] I'm thinking about, I have two kids, the younger one is just getting all four of his molars in now. And, and so he's a bit of a terror, but I remember the, with the older one, as most first-time parents do, we try to plan everything out and then, and then sure enough, nothing actually goes to plan.
[00:27:37] And what I, what we learned was that really, when you're raising kids or when you're raising, building a code base, It's really about being able to adapt in healthy ways and being able to react and to sort of really close the loop, and some things will go better than you expected. Some things will go worse than you expected, and being able to sort of be ready for that and handle that. I think that is actually it's really important.
[00:28:02] And so people go into, testing and code documentation, trying to come up with rules. Like I want 80% test coverage, or I want, every function in this folder to be documented.
[00:28:16] And I mean, the rules are fine, but actually what's even more important is what you both touched on, which is being able to self-heal. So if, if you have a, some failure in your code base, that should turn into a test, right? It's like, whatever you had to fix to fix that failure should be part of a test.
[00:28:37] And, and similarly, when someone comes to you and they say, look, no one on the team understands what this code that this person wrote three years ago is doing, and it's holding everyone back. Well then, not only are we going to rewrite that, we're also going to document it because clearly we, we need to heal from that.
[00:28:57] And so, yeah, that is, is extremely important. It's really about setting up the right adaptive processes.
[00:29:05] Omer Rosenbaum: I agree. I also think that when you read through documentation that has gone out of date, because in most cases, the commendation doesn't leave in parallel with a code. So the code evolves and the documentation doesn't, and then someone reads through it and says, okay, everything here is outdated. Then that person should also update the documentation, or you should deploy tools that help you with that test, that makes sure that the documentation still matches the current state of the code as it evolves.
[00:29:35] Tim Post: Even if the documentation isn't fully updated, it's really help for me to say, if I'm onboarding something or to doing something. Because as, as programmers, we tend to blame ourselves when things go wrong, I broke it, and that tends to happen. If you can do something that says, Hey look, the documentation that you're currently working with, we believe it to be mostly current, but examples may not line up with what you find in the code.
[00:30:04] That is a big deal for me, because I am going to really stress out. If I go looking, searching through the code for this example that you have there. And I can't find it. I'm going to think, do I have the right repo? Am I even looking at the right thing? Oh my God, how did I even get hired here? That's the sort of Imposter Syndrome that can really start to creep into you. If you don't actively try to chase it out.
[00:30:24] So even if everything isn't pristine, just some sort of indication that, it's not you it's us, very subtly in that documentation, can really, really, really be helpful. Because as we know, stress is the enemy of creativity and learning. If you're stressed out, you start looking for things that you want to shut out. That is the opposite of what you should be doing.
[00:30:43] And we talk about onboarding as if like it only happens once or twice when you join a company. If the company that you're joining has like 35 microservices running, you're going to onboard, 35 times a month because code bases are going to change drastically, almost every single day.
[00:31:00] So it's not the occasional problem that it used to be when it comes to internal code. We would often complain about library code, not being very well documented if it's third party. But our internal code itself, the documentation on that is much more important than I think it ever used to be.
[00:31:14] Omer Rosenbaum: Right. And I think it has become much more complex in recent years, in that you have many multi repos nowadays and many microservices, and sometimes you read some code and then you don't even understand what to interact with, because the code that's responsible for interacting with it lives within another repository, or maybe it's a third-party service that is running somewhere else.
[00:31:36] And you don't even know where it is, or you don't even know where to look for it to get and understand what's going on behind the scenes. So as machines and systems become more and more complex, I think the importance of documentation is even bigger, nowadays.
[00:31:53] Tim Post: A real-world example of that is like, you want to do some sort of debugging on like this huge Java data broker service that's running somewhere and unbeknownst to you, this thing needs like 128 gigabytes in order to run.
[00:32:06] And you tried debugging it on your laptop, and you're wondering why it won't work. And you waste, like two days until someone finally tells you, look, you're not actually going to be able to run that locally. Here's how you'd need to debug that. Having that debugging guide handy when I'm first going, just some breadcrumbs for that would be huge.
[00:32:24] And this is part of the, what I call the tacit knowledge. That, a really good example of it. If you gas up your car, you put the nozzle, you stick it in your tank, right? And then you squeeze the lever, you know where the gas is going. It's going into your gas tank. That's very deliberate. Now, the way that documentation works, if you can imagine you just get the nozzle and you sort of squirted on the roof of the car and you hope the gas soaks in where it needs to go somewhere, (laugh) that is actually the song and dance that we make our fellow programmers do.
[00:32:54] And we really need to stop doing that because it's not fair to them. And it wastes a lot of time.
[00:32:59] Omer Rosenbaum: Right. I think in your story, Tim, actually, someone on your team actually knew that you shouldn't be using that laptop to debug that thing, right?
[00:33:06] Tim Post: Yeah. And they, someone could have stopped you from pouring gas all over your car.
[00:33:10] I mean, it's not only a waste of time, but it's also, for the new person, it feels as if you've really haven't considered them in the grand scheme of things of how you're going. And that's not very inclusive. It's not very welcoming. It's not, it's not what we should be doing to each other. So really good example of that.
[00:33:26] And the, the self-healing part really helps that, if something comes and kicks you in the backside and says, okay, you have updated your major version in this particular file, which means you've done a big release. And we haven't looked at any of this documentation that talks about the why and the debugging and setting up your development environment. That is part of the automation that, that actually has to happen.
[00:33:51] And I believe, I'm a big fan of thinking that there can be true automation, even when you have to depend on human beings to do things. It does actually work.
[00:33:59] Jason Gauci: Yeah. That makes, that all makes a ton of sense. So I think we talked a lot about what good documentation is and in terms of why, one of the, the biggest reason is what we all touched on that, even if you write the code and someone else, assuming you have some type of peer review process, if someone else's peer reviewing it right off the bat, twice, as many people have read the code, right.
[00:34:21] Because you've read it since you're the author and the peer reviewer has read it, and it's probably going to be an order of magnitude. More people have read it than I've written it. And so we kind of take that for granted. We take for granted just how many people are actually going to read this code and how many times they're going to read it.
[00:34:39] And the same is true for documentation. And so this, this helps a lot of the insecurity and the stress that people feel when they're onboarding.
[00:34:48] Another thing which is I think going to become more and more important is that is a documentation that sets up contracts between, between or among engineers. And that, now we've been working remote for over a year now. And so, without being able to tap that person on the shoulder and say, Hey, you know, your function, can you also make it accept floats because I have some fractions I need to pass it. And you, you can't do that anymore.
[00:35:11] You can IM somebody, but maybe they won't get to it until tomorrow. They won't even see your IM. And so, I think it's really important going forward that we figure out a way to, especially among teams that are distributed, you set up contracts and documentation could be a really good way to do that.
[00:35:28] Tim Post: It definitely can be, absolutely can be, but what's even worse than that scenario is if that got implemented like three months ago and you didn't know it and you were still doing it like the hard way. And the only thing that broke there was because it just wasn't documented, that this was the new behavior yet.
[00:35:43] So it absolutely needs to happen even in organizations that are truly remote first. And by that, I mean, almost all of your critical path discussions happen in Slack or whatever you use to communicate in order to talk among each other, instead of everyone huddles over in the office and like half the people, in Brazil or wherever aren't part of the conversation and that, that can really happen a lot in organizations, unless you're very deliberate about it.
[00:36:08] Cool.
[00:36:09] Jason Gauci: And so we should definitely talk about tools, but independent for now. Just, just suspending the discussion on tools for a moment. What are general practices? Like how do people go about writing good documentation? What is sort of like the mindset, and is it something where it's totally in the code?
[00:36:28] Like, how do you reconcile your code versus, a Wiki versus your 10 other media? What are good practices there?
[00:36:37] Tim Post: I think the biggest one is when you write it. I get asked that a lot. Like when should I write my documentation? And it's like, well, as soon as the thing that you're working on starts looking, it's taken a similar shape a few times.
[00:36:52] You've solidified the code. You solidified the behavior. You've, you've got, pretty much everything mapped out. At that point, you should really start to write documentation, because documentation that I write about, for I'm right now, I'm reading a command line tool in Python. So as soon as before I released this, I'm going to make sure that it has a nice help section. And that the code in my flow is documented there.
[00:37:15] If I write that documentation in two days, when I release this thing, it's going to be good. Everything that I was thinking top of mind is going to be in that documentation. And for my future self, who you identified very early on, when we started talking, there's going to be reminders there, of everything that I was thinking at the time.
[00:37:30] And it is going to be a higher quality than anything I could write three months from now, bar none, even if I'm the same person, I wrote the same tool, my documentation for it is always going to be better when it's fresh in mind.
[00:37:42] So whatever flow that you adopt, it should be centered on basically writing it when it's fresh. If you don't do that, number one, it's not as good, and number two, if you can justify procrastinating and not writing it today, then you will also be able to justify procrastinating and not writing it tomorrow. And then the next thing you know, it's three months from now and you're facing another sprint to go write about documentation, about stuff that you don't really remember.
[00:38:07] Jason Gauci: Yup. I have another rule that I follow, which is, if I see something that an elementary coder wouldn't understand, that I ask if there's some documentation next to that.
[00:38:18] So for example, we write most, mostly in Python and in Python, there's this thing you can do these, I forgot what the name of it is. It's the functions that have the underscores in the beginning. Like there's a term for kind of all of those. Like the most common one is like __niche. Right?
[00:38:33] But there's other ones, like in this case, it's __getattr. And you can use this, so if you have a object in Python, like Fu, you can actually call like fu.x, fu.y, fu.z, even if these aren't numbers of your class, and if they're missing, it will call this function.
[00:38:53] And so you could effectively do fu.anything, and it will actually, it won't, it will, it will do something. It will go into that function and something will happen...
[00:39:02] Tim Post: Overloading.
[00:39:02] Jason Gauci: Yeah. Yeah. And so I think it's not like a magic methods or something that, that whole category like __eq and all of that.
[00:39:09] But someone used that and, and I just said, Hey, can we just document why we're using that? Because it's, it's going to add cognitive overhead. Right? And so in this case, it was had to do with overloading, a class that we didn't own. And so there's a good reason to do it.
[00:39:25] But anytime you have to do something that is, you know, he's starting to get into the more advanced parts of the language. That's where I really, you should have really high density of documentation on day one, like right when the code goes in.
[00:39:38] And so I've had cases where, right when the code went in, there's some comments saying yeah, you know, we're, we're dividing by this magic number because it's faster than square root. Like that needs a comment, because you'll look back and you'll say, yeah, why, why am I dividing by 67,000? Like, it doesn't make it in a function called square root. Right. Right.
[00:39:59] And so, so yeah, I think, I think some code and you'll know right away, some code needs to be documented, zero day. And then, and then to your point, I, as soon as you start kind of having the whole idea, then you could really kind of document everything else too.
[00:40:14] Tim Post: Well, you just said trick something that I think is really good to bring to light. And it coming back to sort of the Imposter Syndrome thing, a lot of engineers that I know would not ask questions about that.
[00:40:23] They would just say, oh, that's, that's how you do it. It seems really weird to me, but I don't know enough to say that this is not right or even questionable, and therefore I'm not even going to say anything about it. And then it's going to trip up the next 15 people that, that hit it.
[00:40:37] Omer Rosenbaum: Right. And I think Jason, that's a great example of where inline comments or comments in your code are actually the right way to go.
[00:40:44] You have a specific client that does something like, dividing a number by 67,000. And no one is probably going to know why you did that at that time, so you're going to add in line, what's going on. This is the kind of things that you want to document in line within the code.
[00:41:03] I think for other cases like flows between different code files, between different functions, or nowadays between different repositories.
[00:41:14] What you want to do is document not within the code itself, but in external document that may reside within the code base, but still not next to the code lines themselves. However, people tend to approach those documents in a way that's more literal. So they would just write a lot of texts. And then it's also hard for them to start writing because they don't even know where to start.
[00:41:37] And also it tends to become not as practical, because as a consumer of that document, I just read a lot of texts and I don't know where it actually references the code. So what we encourage people to do is actually include references to the code. And by that, I mean, snippets of the code itself, for example, also function names, variable names, anything that would actually help the reader have a walkthrough experience.
[00:42:02] So I would want to read the document and feel like Tim is tending by my side, explaining to me what's happening here. And I did this because of that. And this line here does this, and then it calls this function within this repository and why I did it and so on.
[00:42:19] So for that, you might even want to start by looking at the code itself, identifying what parts of it you want to explain, or what flow you're trying to convey. And then within that code, go select parts of the code itself and add comments to it. Not within the code, but on an external document, including parts of that code.
[00:42:42] Jason Gauci: Yeah. That's a really good call out. I feel like when it comes to that side of it, people kind of fail in both ways.
[00:42:49] In one way,, there's a documentation in the code, which is nice for that purpose. And then there's just, as you said, a wall of text, and it's very hard to map this, this wall of prose back to the code base.
[00:43:02] And then on the other end of the spectrum, if someone gets their hands on Stinx or a, one of these tools, and they auto-generate a 10,000 HTML files, but, but because they're auto-generated and 99.9% of the code isn't documented, you end up with just all this auto-generated texts that is just agoraphobic.
[00:43:24] Like, no, one's going to read any of that. And it also kind of people don't--
[00:43:28] Omer Rosenbaum: And it's without context.
[00:43:30] Jason Gauci: Yeah. And people don't document it because it's now so big. And if I, even if I documented it, who's going to know what's documented? And so that that's two ways in which I've seen this fail.
[00:43:41] Tim Post: With the code comments, you should absolutely be doing that.
[00:43:44] You should, you should be doing that for the person that you're going to be in five minutes, and you should as well be doing that to anyone else that ever has to come across the, the code itself.
[00:43:53] But those comments are sort of like rungs on the ladder and they need, they need something to stand on. They need the higher level narrative to guide people through that.
[00:44:03] And a good example is, how do I make something configurable? Like I need to add a configuration value to the config file in this application where the code pass, I need to do that. All of the great code document, if everything is documented comments there, that's awesome. But people tend to start their discovery on an endeavor.
[00:44:24] So having those things available, those common paths, or even uncommon paths, if they lead you through strange places, is thoroughly helpful for people to onboard with. And make sure that that has all these examples that you have in your code.
[00:44:39] If you need to show people how to, what dependencies do they need to inject when they insensiate the class. And then, oh, by the way, we use a lot of overloading here because Redis has so many verbs, we can't be bothered to implement them all since the requests are all handled the same. That would be a really good place to put that in there too. And that is the walkthrough that you need. If you need to, maybe you, you want to cache a value in your web app instead of serving it all the time for performance reasons, that is a perfectly normal thing for someone to be assigned to do when they get to work in the morning.
[00:45:12] And if you don't have that there half of their day is just going to be looking for what's relevant and they're not even going to get into the code yet.
[00:45:20] Jason Gauci: Yeah, that totally makes sense. So how do people go about doing that? I mean, we talked about kind of these two extremes, but, but if you wanted something with better balance, so if you want to be able to write a story, but have that story, reference the code.
[00:45:36] Like, how do people go about building something like that? I mean, it's hard to kind of like deep link into a code base. Right.
[00:45:43] Omer Rosenbaum: Right. So basically what we first suggest people do is select parts of the code base and then reference them. There are a few ways to do that.
[00:45:53] The easiest way would be to copy paste snippets off the code to your document. And just talk about that. The downside to that, and we can talk about this later is that it will, may indeed become out of sync quite quickly. But it does ease up the process of explaining the flow. You start by selecting the code you want to talk about, copy-pasting it to a document. And then from the document you describe the flow itself.
[00:46:17] Also by starting with a code, it makes it much easier for you as a writer to know everything you want to elaborate on, what's important and what is not. Also, I think Tim mentioned before the inline comments in various use cases, and perhaps you have a specific function and you explain the logic of that function in one place, but those documents help you understand what this function does individually broader scope of a full flow.
[00:46:42] And you may be doing different things in different flows. I mean, the function itself will obviously have the same code, so it will technically do the same thing, but for different purposes. And that's the thing that's more insightful or more important for people to understand, usually, when they go through the entire flow of your program.
[00:46:59] Tim Post: One of the biggest telltale signs of not having great documentation is not seeing code reused when it should be.
[00:47:05] It means the people, there's no understanding that there was already something there that they could have used and adapted a little bit, because it just wasn't explained to them.
[00:47:12] Jason Gauci: Oh, that is really interesting. Yeah. That's a really fascinating, really fascinating metric. Yeah. I mean, there's a whole, there's a whole tangent on, on what are good sort of metrics that you should capture when running a software team, but yeah, that is, that is the one that I would want to add to the list. I love that idea. I mean, it's a little bit hard to measure, right? To measure when code could have been reused, but it's doable.
[00:47:34] Tim Post: It's a balance too. It depends on your you're setting on what you're doing. In microservices, modern systems we can just call them, some conventional wisdom goes out the window a little bit. One of the benefits of microservices is Team A can use a different thread library than Team B. Right? So the whole dry thing doesn't always hold as much water as it used to. So it's not always like a telltale sign, but it can be, if you, if you take the context of everything else into place, it's one of the things that you should definitely watch out for.
[00:48:05] Jason Gauci: Cool. That makes sense. So let's dive into, into Swimm here. So kind of give us a brief overview. We have a good idea of why you should write documentation. What are good practices, how you should write documentation and what documentation is, how does Swimm help with, with these things?
[00:48:21] Omer Rosenbaum: So Swimm encourages doing exactly what we just described, and that is creating code couple documentation.
[00:48:28] And by that again, I mean, document that actually include references to the code itself. So when you create documentation with Swimm, we help you include those code snippets or specific references to functions or to file paths or other references from within the code. But then one of the downsides of doing that without the appropriate tools would be that those references become quickly out of date.
[00:48:53] What we do at Swimm is we track the changes to the code base as part of your CI or other hooks, like a githook, and then we help you by notifying you when the relevant code changed. And in case the change that had been made is not significant, or doesn't really change the meaning of the document or the general flow you're trying to describe, we automatically suggest an update to the documentation.
[00:49:22] But if the change is really significant and drastic, for example, you documented an entire module and it doesn't exist anymore, then we tell you, okay, look, this part here isn't up-to-date anymore. It's just incorrect. Please stop right now, not in a few months after the documentation is outdated, but while you are making the change and explain why you changed it and what's the current state and what's right about it. So basically we help you create documentation that we believe makes sense for developers to consume, and also to keep it up to date.
[00:50:00] Jason Gauci: That makes sense. So stepping back a little bit. So, so, most times if you're using something like GitHub, that's great, but even if you're at a private enterprise, you'll have some web view into your source control. There'll be some, hopefully some type of server you can, you can visit on your intranet, and you can get a hyperlink to a file or even a specific range of lines in a file.
[00:50:26] And so you might say, well, if I'm going to build this documentation, I would create these, the, I would add these links to line 90 to a hundred. I'm going to reference that block of code as I'm writing my documentation, this is the broader documentation.
[00:50:42] But then as you said, let's say someone adds a new function and they add it at line 80. Now your function got pushed down, maybe a hundred lines. And so if you don't update that link, it's not going to make any sense. And so what you're saying is that Swimm does the right bookkeeping so that you don't have to keep tabs on all of that, which is almost impossible if you're working with a large team.
[00:51:06] Right. I mean, it's very hard for someone to know that you've put a hyperlink below them in any line they add we'll break that link. So, so Swimm takes care of a lot of that. And in cases where it, isn't sort of a very clear like an operational transform, in those cases you can kind of alert people and say, yeah, this, this functioning reference is totally gone or it's someone completely rewrote it and now it's a hundred lines. And so you should probably take a look at it again.
[00:51:35] Omer Rosenbaum: Correct. So one part is the bookkeeping of your name, date. So that could be different client numbers. It could be a rename or just moving the file somewhere else.
[00:51:43] Something that happens quite frequently is that people perform minor refactoring. So for example, you have a function that you try to describe in your document and it consists of 200 lines and someone just pushed, I know, renamed one variable or edit one if to capture a specific edge case. The documentation still holds, but you still want to make sure that it captures everything that is relevant. You don't want to show code that is not up to date because then developers will not believe that the documentation is up to date and captures what it should capture.
[00:52:18] So also in these cases, we suggest the changes that should be made. For example, now you need to include these edge cases as well. But yeah, in case the code really changed drastically, we'll just tell you, please pause now and reconsider your documentation and make it up to date again.
[00:52:36] Another approach, or sorry, another advantage of having code coupled documentation is that actually we know from within the code, what documentation covers it. So for example, while you're coding within your ID, for example, we can show you, wait, this function here has a document describing it. And as opposed to inline comments, these document perhaps explains how this function takes a role in a broader flow.
[00:53:04] Or maybe this function is actually described in multiple documents, each one describing a different flow. So you may want to be aware of that because as you mentioned before, if the documentation exists and no one knows it exists when they need to, then it doesn't really help a lot.
[00:53:21] Jason Gauci: Yeah, that makes sense. I know I would actually love to ask you, you both of good examples of this on the web, but one example that I personally feel is really good is the PyTorch Documentation.
[00:53:33] They have, they have the whole auto-generated thing going on and you can go, I think they call it the API section of their documentation. You can go there and you can, you can actually browse the entire source tree with comments. And there's also a, auto-generated like markdown HTML files for every file.
[00:53:51] But then they have these narratives, like, like here's how automatic differentiation works. Here's how a sparse tensors work. Right? In those narratives, they're linking back to either the API or the, or the source. I don't remember exactly how that works, but, but they have both and they're both really important.
[00:54:11] And actually I love the idea you just mentioned. I mean, it would be great if, while, let's say you choose an auto grad system, you choose, you choose Adam or adadelta or one of these things, and you're in visual studio code and you type torch.optim.adam, right then and there, maybe they could pop up a little box.
[00:54:31] In addition to the box that tells you the arguments, which you might already know. I mean, there, there could be a little boxing, here's how automatic differentiation works and gives you kind of that more high level information. That's really important.
[00:54:45] Tim Post: I've seen it. A lot of people pick on PHP, but the PHP community is really, really, really good because of some of the quirks within the language itself.
[00:54:54] If you go to a lot of the PHP frameworks out there, You can find really, really good documentation. That's one of the ways that these open-source frameworks compete. How well-documented they are is a big determination of, of which one your team is likely to use.
[00:55:10] And PHP codeigniter, as well as laravel and symfony can do deep dives into Insync. Look, this is to overcome a language feature or, or something that isn't implemented in the language yet. Or this is because of a, a way that the language works, that that, that we're implementing it this way. And those things, those things have been called out first and foremost, right where you would need to have it before you start scratching your head, wondering what you were doing wrong. So those are, those are really good examples of documentation.
[00:55:40] And we in the microservices world, we're kind of missing that. We don't have that anymore, because frameworks are being thrown out there and we're writing lighter code that that goes a lot faster, but at the same time we are giving up a lot of documentation that was already written for us about, about the stack that we're using.
[00:55:59] And I don't think that the, the, the true cost of that is conceptualized by CTOs and CIOs more than it should be.
[00:56:10] Jason Gauci: Yeah. That makes sense. I think, I think, maybe post hoc, they're looking and saying, why did our productivity go down the drain, right. When what they should be doing is being like defensive and kind of looking ahead and saying, having the right metrics, we talked about saying, okay, well, why is the health of our documentation going down? And then that would allow you to be proactive.
[00:56:34] Tim Post: My favorite features of Swimm is the CLI tools that we have for it, which will actually tell you if your coverage on a given repository has gone down. If you basically set a mark there to what you want to be. As far as a score between zero out of a hundred, how well-documented are you, you can check that easily.
[00:56:53] And it's also really great that you can do that at the pre-commit phase, which I think is good. Number one, because I just ran Twitter poll, not that long ago, about how long it takes for CIs to, to actually run if you're doing a full build. And the answer to that was anywhere between five minutes and, you know, hours, for that to run.
[00:57:13] So I think some teams might not be all that eager to put yet one more check in the CIA that's causing people to do work, but if you run it locally, you can make sure that your documentation is up to date right when you need to update it, before you even do the PR at that process, when the lints run and, you know, spaces get converted into tabs, as, as it should be. I don't want to start that war on this podcast, though. (laugh)
[00:57:39] Jason Gauci: We actually had a, not a whole episode, but we had an editor episode where we, I think I'm not sure if Patrick and I agreed or not, but either way there's like heated discussion about it. (laugh)
[00:57:50] Tim Post: One of the tightly contentious areas of software development that will always be, it will always be there. That is like the bike shed of programming. (laugh)
[00:57:58] But anyway, one of the things that I like about just the design of Swimm is it's all of the little tools that you need to couple all this stuff together in the waste that we're talking about.
[00:58:07] You could do it other ways. I mean, there's other ways that you could do it. You could look at, file times on when documentation was last edited. That's a great way to pick up stuff. That's probably starting to stink a little bit. You can trigger documentation builds based on major vert, major new versions and stuff like that. Swimm just does it in a way that doesn't presents you with the least resistance to actually keeping it up to date.
[00:58:30] Omer Rosenbaum: Think Jason beforehand, you mentioned that when something goes wrong, nowadays we edit test to cover this case. And I think that happens partially because the world of testing and continuous integration has evolved so much in recent years and we're trying to get the same documentation.
[00:58:49] So we want to help you create documentation while you write your code and also make sure continuously that it's still up to date and that it covers everything you want it to cover. I think that is very similar to testing, in that manner.
[00:59:03] Jason Gauci: Yeah, totally makes sense. I think, I think having the right, the right metrics and getting that instantaneous feedback is so important for building the right incentives.
[00:59:13] And I think for test, as you said, tests have, I wouldn't say they've been around longer, but people have spent, maybe more time and energy on figuring out how to write software tests and software documentation. And so they've set up those right incentives.
[00:59:28] And most of the things I work on are, have been open-sourced and we'll have people who will just increase our test coverage and it could be maybe they're in the middle of learning how our repository works and it's just, you get this instant gratification for doing that. You feel like you've really contributed, 'cause you just see that result. And so getting documentation into that flywheel is, is super powerful,
[00:59:50] Omer Rosenbaum: Right. I think it's also a means of gamification in some means, and you get lake this goal you strive for, but also it helps you visually see what parts of your code base are currently visible to people who are new to it.
[01:00:04] So for example, if you are able to see that this module or this folder, or this file has corresponding documentation, and these files doesn't, that you know that for the first file, you don't need to worry as much. And actually we've also seen it with teams where knowledge is very much concentrated. So let's say you have one person who has been responsible for a module for a year now, and only that person knows what's been going on in this folder.
[01:00:32] And if that person just leaves the company tomorrow, what would happen to all the files, there, to all the knowledge? And again, it's not just the code that leaves there now, all the decisions that that person has made in the process of creating this code, maybe the path he hasn't taken and the things he hasn't implemented because he thought about them, but he had really good reasons not to implement. So all of that knowledge is going to be gone.
[01:00:58] And if you have tools that show you that currently all the knowledge of the team is concentrated on one person for a specific folder or module or repository. Then it also gives you an incentive to know that you need to invest now in creating documentation for that specific part.
[01:01:16] Jason Gauci: Yeah. That's a good call. It, that seems like a nightmare scenario, right? Where. Where one person kind of owns a whole directory or something and no one else really has any, they all have to kind of trust that person. And that person goes on PTO. Everyone just has to wait until they come back to it to edit stuff in that folder.
[01:01:32] What is actually, a bit of a sidetrack here, but what is, do you have any horror stories, you know, documentation or just code health horror stories that you'd want to share that that pur audience needs to get a kick out of?
[01:01:45] Tim Post: Hmm. Um, I have an interesting story about some jellyfish.
[01:01:49] Jason Gauci: Sure. Let's hear it. (laugh) Okay.
[01:01:51] Tim Post: So I was working in embedded systems. It's one of my hobbies, and occasionally I do some consulting to help people do it.
[01:02:01] Jason Gauci: So is this like Arduino type stuff?
[01:02:03] Tim Post: Arduino, Gumstix, Raspberry Pis. And that there's also some industrial, single board computers out there, different varying architecture.
[01:02:11] Jason Gauci: Cool, cool. Very nice.
[01:02:12] Tim Post: Getting operating systems into small places. You know, when you've got like that forming a bite ceiling is really, it reminds me of poking away on my own 3d6. So it's a lot of fun to do sometimes.
[01:02:23] And there was a power company in Asia that had a problem with jellyfish. And the problem was the fresh water intake for the turbines that cooled the power plant. The impellers would get clogged if they came on at the wrong time, depending on where the sea levels were. And it would literally gum up the works and it was bad. So they started deploying these fish finding sensors in order to, to combat that, so that if there were like a whole school of fish going by, the plant could, not taking as much water right then, and then, it wouldn't be so disruptive to the environment.
[01:03:00] Systems like that, that you write, and you think, okay, this is going to be like a, a temporary thing, because the ocean currents are always changing and stuff like that, turns out not to be. And then it turns out that, pillars are built on top of something really, really rickety that, that you implemented a long time ago as a quick workaround.
[01:03:24] And that tends to happen all the time in software, but in particular where your, where your code is like running submerged undersea where you can't really manage it. It is absolutely critical that you have documented ways to restart these systems and even let people know that these systems existed. And so I helped with getting the fish finders programmed, and they were communicating over a one wire bus back to a receiver and they were working well.
[01:03:54] And I got a, I got a frantic phone call 10 years after I had last looked at that code, with questions about it. And apparently no one knows that those things were deployed. No one knew what they were doing. And the only thing they could find was a phone number that I was almost not in possession of any more. So luckily they were able to to reach me to find out why seawater wasn't getting pulled in, in that part of the control loop.
[01:04:19] But that was just one of the interesting things where you can... if you, if you're not very, very, very deliberate about it and you don't do it right then, there's a very, very, very good chance that someone is going to regret that. And it may or may not be you.
[01:04:32] Jason Gauci: Yeah, that's a really good call-out, Patrick and I worked, they called it the Advanced Research lab in a, at another company. And that's how, that's how we originally met many years ago. I think what I don't know, 13 years ago or something now.
[01:04:46] So at the time, neural networks were a pariah. Like if you, if you believed in neural networks, it was almost impossible to graduate. Marvin Minsky, all his people had been totally discredited and nobody thought neural networks or deep learning was ever going to amount to anything. And here we are in this lab trying to try to get this up and running.
[01:05:04] And now fast forward, I was talking to, I went back to the East Coast and I was talking to some friends of mine, some former colleagues, and they said, yeah, they're still using some of the codewe wrote back when we thought no one was ever going to read this or do anything with it. And I don't even know if we use source control because we were, we just felt like, well, here's this, here's this throwaway idea that no one believes in. And so you just never ever know. And it's, yeah, it's so important to have some type of way to kind of continue that because it could end up being a, you ended up saving the jellyfish ecosystem or writing something that a lot of people use a long time later.
[01:05:42] Tim Post: I've talked to people that, that implemented things that, like the PalmPilot, if you remember those, the Palm III with that LCD and the stylus, and there are people to this day that are using code that we wrote for Palm V HotSync to Linux, which has not been supported by Palm for probably 20 years now. (laugh)
[01:06:02] So yeah, it's, it's just amazing what, what stays out there and what continues to provide value to people long after you do it. And that's one of the reasons why we get into this. And one of the reasons why open source is so much fun because you, I mean, you never know when you're going to end up being, code that you wrote when you were a very different person, ends up, saving someone a lot of time. It's great.
[01:06:21] Omer Rosenbaum: I remember one time back in the army days where a friend called me to help him debug this operational system where messages just didn't come through. So we knew they were being sent from one end, and we needed to receive them at the other end, and specifically, those were messages who are prioritized as the most important and urgent to be sent. And we couldn't receive them.
[01:06:44] And the person who had been responsible for that system left a few months before. So we had to just try and figure out everything on our own, and it took some time, but in the end we found out that one end of the system, or in other words, one developer assumed that one meant the most urgent and 10 meant the least urgent. And the other developer responsible for the other end assumed it was just the opposite case.
[01:07:13] Jason Gauci: Oh no. (laugh)
[01:07:14] Omer Rosenbaum: Yeah. There was no documentation helping us there. And yeah, it actually got a lot of important messages to get lost in the wait.
[01:07:22] Jason Gauci: Yeah. That that's that's definitely a documentation nightmare.
[01:07:26] So going to Swimm. So imagine there's, there's sort of two ends of the spectrum. On one end, there is somebody who is just starting out, they're in high school or college and they're looking for something that is ideally free, or if not free, just very, very cost efficient, and something for a personal project that they have on GitHub, probably on a, on a public repository.
[01:07:51] And then on the other end of the spectrum, there are the folks who are in an industry, and, and they, they have source control. That is their intellectual property that they're very protective over and they have an internal, maybe they have an internal deployment of GitLab or something like that.
[01:08:05] And so what can Swimm offer these two kinds of audiences?
[01:08:10] Omer Rosenbaum: Swimm has been and will be free for open source projects. So whenever anyone has a personal project or just an open source project, they can use Swimm for free. And for enterprises we have multiple solutions. Some of them mean that we don't actually get access to the code base at all. So clients who find it really important not to give access can be safe and secure.
[01:08:37] Jason Gauci: Cool. So how does that, the first one is amazing. So people, definitely check it out. We'll have links in the show notes and all of that. So if you are out there and you're a hobbyist, check this out, you'd be amazed, especially if you're a PhD student or if you're doing your senior design project, if it's something that, that has legs. Right?
[01:08:56] I still, my PhD project still gets a lot of stars on GitHub, and that code is absolutely atrocious. So, you want to build something really nice. Also, it's going to make your resume look good. And so, and so definitely check out the free version. That's a, that's a no brainer.
[01:09:11] Jumping into the, into the Enterprise. How does that work? Like if someone wants to use Swimm, but they, they have very strict kind of IP rules or, or, they're, they don't want to go through, but jump through a bunch of hoops to get approval. How would they go about doing that? Is it something where they deploy it on their own cluster? How does it work?
[01:09:31] Tim Post: It's an app that's written in Electron, so it's highly portable. And Swimm works with Git as the backend for the storage, and it will create a .directory, .SWM inside the repo, similar to the .git directory. And that's where everything is staged.
[01:09:48] On our side. We don't really get anything about your code or anything like that. All we get is some relational mapping so that we know that, this playlist of documentation is tied to this repository. So, but it's all hashes on our site, so they don't have to worry about that. And it's currently very beta right now, but for consuming the documentation, Swimm has the ability to export to the documentation files that we create into markdown format.
[01:10:15] And we're currently working with ways to, to integrate those into internet apps and other, docusaurus and things that are popular platforms for, for consuming developer documentation, so that you don't absolutely have to have access to the repo in order to read it too. That's a big use case that we are, we're trying very hard to support.
[01:10:33] Jason Gauci: Oh, that makes sense. Okay. So basically, and I think you touched on this, but I didn't put it all together until now. So, because the documentation, or let's say, whatever, like the things that the artifacts for Swimm are in the repository, then you don't also need some centralized service, that store a bunch of information.
[01:10:52] So each person runs the Swimm desktop app, and effectively it's communicating through the commits to the Git repository. Is that, did I get that right?
[01:11:01] Tim Post: To a certain extent, yes. What Swimm will do is it'll understand a concept of teams and which repositories are tied to which team. So Swimm will know if you have all of the repositories installed on your local machine because we'd be able to find them, or it will tell you, Hey, you need to, to pull from the central repo in order to get the up-to-date docs or, Hey, you're missing a repository. If you want to install it, here's the command that you need to run to clone the repo for your sites so that you can get it.
[01:11:28] And Swimm also relies on Git for pushing. So there's centralization to the point that it exists in Git. So obviously if you write documentation, it's stored in your repo and you want your team to be able to consume it, you need to be able to put it in a place where they can pull it.
[01:11:44] Likewise, if you're working on documentation at a branch and you want people to be able to assume it they'll either have to check out your branch or you'll have to merge that with the master batch.
[01:11:52] Omer Rosenbaum: Right. So what it basically means is that if someone has access to the repository, then they also have access to the documentation. But if they don't have access to the repo, they don't have access to the documentation. And it's not something that Swimm handles, but something that you handle on your own, for example, by using GitHub.
[01:12:10] Jason Gauci: Yeah. Totally makes sense. And so, okay, that makes sense. So, if someone is working for enterprise company, they want to try out Swimm, how would they go about doing that?
[01:12:20] Is it something where they, on their own, is there a trial or they, they maybe swipe their credit card and they try it out on their own? Or is it something where you kind of, you have to go to your software engineering director and, and kind of lobby to, to start using it.
[01:12:37] Omer Rosenbaum: So currently we are in beta. So you reach out to us on the website and, but you are always welcome to start working on your own for free, and also for Team, it's going to be for free. So you're able to experience with the product, create documentation, share it with people, see that it remains up to date as the code evolves and to get some value of using Swimm before swiping a credit card or something like that.
[01:13:03] So at the beginning it's for free, and we are also very eager to help you getting started and seeing how people use Swimm and what kind of great documentation they create and then consume using Swimm.
[01:13:14] Jason Gauci: Cool. That makes sense. So, yeah, I think this is amazing. Everyone should, should definitely check this out.
[01:13:19] We'll have, have links to the show in the show notes, all of that. So in the show notes, for people who don't know are, are linked from usually the, depending on your podcast player, there's almost always some kind of details section. And then we always put a link to the show notes there.
[01:13:34] Cool. So let's jump into Swimm a little bit as a company.
[01:13:37] So how old is Swimm, when and how is Swimm sort of set up, like, is it a distributed company? Is it what sort of, that, that whole story like.
[01:13:47] Omer Rosenbaum: So Swimm was founded in September, 2019, so one and a half years ago. And we started and based in Israel, and actually our first hires were onboarded using Swimm and during COVID-19.
[01:14:03] And at that time it was the first lockdown here in Israel. Everyone was freaking out. So people were being onboarded remotely, which back then seemed a bit not as common as today, I would say. So we were actually pretty lucky to have the very first version of Swimm to use for onboarding our few first hires.
[01:14:25] So we started semi-remotely. So most of the first hires started in Israel, but we started adding people from the US quite early on. Tim, of course. And also we have a few other members there and also we have one developer joining us from Germany now. So the team is semi-distributed, I would say at this point.
[01:14:47] Jason Gauci: Cool. And so what is a typical day like for, for an engineer at Swimm, would you use to communicate and, what is something that you think would be, would be kind of interesting and makes your company kind of stand out from a kind of day to day perspective?
[01:15:03] Omer Rosenbaum: So I think one of the first things we do every day, so we have a daily session, which is very common. And in the beginning we have a section, we call the "Stranded at Sea." We use a lot of swimming lingo at Swimm.
[01:15:15] Jason Gauci: That makes sense. (laugh) Yeah.
[01:15:16] Omer Rosenbaum: So we have a "Stranded at Sea" section, where everyone is welcome to raise any issue they may have. And I think because we are a company who creates tools for developers, then our developers are also using the product on a day-to-day basis. So they are all opinionated and have a lot of thoughts and new ideas as to how we should create this product as well. So almost every daily session includes some insights about the product itself and how we may evolve, implement, and improve it over time, actually.
[01:15:50] What we also have I have, and I think is quite cool in Swimm straight from the beginning. We have a ritual, we call Swimming Hours. So it's like a seminar, but a Swimenar. We do that every other week. And then one person from the company can take two days to learn something new. It could be a deep dive tech research into something like the internals of Git or a file system or something in Electron or anything related or not exactly related to Swimm, or it could be something else like product issues or anything you're interested with, that you find, other people will find interesting. And then that person gets to share it with the entire team. We usually spend one and a half hours having that talk and then discussing whatever was presented.
[01:16:43] What I also think is cool at Swimm is that, as I said, we use our own product all the time. So we get to create documentation, consume it and update it all the time. And then whenever we go and talk with other companies about it, we can always use our own examples. As we have mentioned beforehand, we don't really know what's going on at clients or users of Swimm. We're not an open-source project because we don't have access to their code, but we also always have examples of how we use it internally.
[01:17:15] Jason Gauci: Cool. Yeah. That makes sense. How do you navigate the time zone difference? So I, I believe, I wanted, so my family is in Italy, and Israel, correct me if I'm wrong. I'm terrible at geography, but Israel is, is yeah, Israel definitely east of Italy, and Italy is eight hours. So, so I don't know where Tim is in the US, but I mean, you're looking at potentially like a 10 hour timezone gap. Right? And so how do you, how do you handle that?
[01:17:41] Tim Post: Seven hours. It's yeah, it's not terrible. I'm actually a terrible example at this because I have not worked in a physical office in I think like, 18 years.
[01:17:52] Jason Gauci: Oh, wow.
[01:17:53] Tim Post: I've been remoting. I mean, remoting is just something that I do, Stack Overflow as a remote-first company. It still is. And when I was working there, I was 13 hours ahead of everybody. I was living in Metro Manila at the time.
[01:18:03] Jason Gauci: Oh, interesting.
[01:18:04] Tim Post: You have to be very deliberate about it and you have to make sure that you, make sure you're in the place where the right information bounces off of you. No matter kind of what time you get to it.
[01:18:14] But the coordination doesn't, it doesn't break. It's easy to do. Occasionally, I might have to get up at like an hour earlier to make an earlier meeting, but the, the coverage, as far as the customers are concerned is almost around the clock, which is great. It actually just around the clock, which is, which is fantastic for them. So it's not too bad.
[01:18:32] If I were on the West Coast, it might be a little bit different. There might not be as much overlap, but with Slack and the internet applications that we have, and everything else available for us to communicate, and with knowledge sharing being such a big part of the DNA of the company to begin with, it really isn't that much of an issue.
[01:18:52] Omer Rosenbaum: I also think that we don't only have time difference, but also a weekly days difference. In Israel we usually work Sundays through Thursdays, and outside Israel in most countries, I believe, people work from Monday through Friday. So we actually have one day where the Israeli side is working and the other sites are not, and vice versa.
[01:19:15] So we actually established a few rituals for that. So for example, on Sundays where only the Israeli side is working, we usually do stuff that are mostly R&D, Internal, and we deploy versions and stuff like that. And they, on Fridays, we usually let product people who are mostly located in the US for now, go over and create mock-ups and do other things that make sense to do on a day where the R&D is not exactly available.
[01:19:43] Jason Gauci: Yeah, that makes a ton of sense. Our ritual is a on Friday evening, we typically break the bill and then we come back on Monday morning. Right. That seems to be the ritual that we've been following for the past few weeks.
[01:19:54] But, but yeah, I think actually, you bring up a really interesting point that, there's all this talk about people not coming back to the office. So I actually ended up, Patrick and I both ended up full-time remote. We ended up both moving back to the towns that our families are in. And so for us, it's going to be, this is a new normal. But even for people who are coming back into the office, a lot of them are saying, I only want to be back three days a week or two days a week or maybe one week on one week off.
[01:20:24] And, and the challenge there is, when you're working with a whole bunch of different teams, the odds that you and someone else, or maybe put another way, the odds that two whole teams are in the office together, even if none of those people are remote, is going to go to zero when we get back to normal or whatever that is, the new normal. The odds that, that two whole teams are in a room together goes to zero, whereas before it was maybe 50%. Right? And so that I think, is going to really revolutionize, I mean, it already is, but it's going to just confirm that that revolution isn't going to go away, because we're never going to be able to line up people in person like we used to.
[01:21:02] Tim Post: No, it's a, it's a value proposition, and the delta is only going to get bigger as time goes on. As people have experienced, even during the pandemic with when everything is essentially just on fire and horrible, we can all agree to that.
[01:21:16] Being close to your family and being able to provide for your family and being able to give the care to the elderly people in your family. Being able to be with your kid. you know, all of the stuff that working remotely provides has shown I think, significant value during the pandemic, that value I think is, has eclipsed comp for companies that will not offer full remote arrangements for their employees.
[01:21:44] So if people are recalling employees back to the office in a way that is absolutely not essential as in, there's no way to become remote first enough for people what to be able to do two jobs like that sustainably, I think people are going to be looking for other jobs because the value of being able to be there, the value of not having that morning commute anymore, is very, very tangible to them in a way that wasn't prior to COVID breaking out.
[01:22:09] So, I'm a little bit biased because I've been doing it for a very long time. And I can't imagine going back to doing it any other way. I think in the future, I'm, I'm not going to be a minority anymore. I think the majority of us are just either going to be remote or some sort of hybrid scenario.
[01:22:25] Omer Rosenbaum: Right. I think for us, the hybrid model has been working really well. And most of the developers now choose to have two days at home and three days working from the office here, usually. And we get just to make sure that everyone is used to that. So we have Zoom sessions all the time. And I think when companies get used to that mindset, then it becomes natural and people also get to see the upsides of it.
[01:22:51] Jason Gauci: Yeah, I totally agree.
[01:22:52] This has been amazing. I really appreciate both of you sharing your time, your experiences. And I feel like we've really motivated the case here just to kind of come full circle, folks out there, if, if you're, a high school or college student, you might think it doesn't make a lot of sense to write documentation for my project that I started today and is due at 6:00 AM tomorrow. And you could be right, but you're going to hit a senior design project. You're going to end up building bigger systems before you graduate. And, and this is where you're going to realize the power of writing documentation. And it's really, really important to kind of get that into your head space now.
[01:23:34] For folks out there who are in the industry, you've probably seen a whole gambit of different ways to do documentation. And you've probably, you know, are just nodding your head at all of these kind of stories, both good and bad. And for everybody out there, you definitely check out this tool. I'm going to check it out later on today. It sounds, it sounds like it really closes the loop on, on a lot of this, and kind of makes it a lot easier.
[01:24:00] So I really appreciate you Omer and Tim both coming on the show, and talking to me, sharing your experiences.
[01:24:07] Tim Post: Oh, it was great to be here.
[01:24:08] Omer Rosenbaum: Yeah. Thanks so much for having us.
[01:24:10] Jason Gauci: Cool. Thanks a lot, everybody out there. Thanks so much for subscribing to us on Patreon. We've been able to get a new hosting provider.
[01:24:19] So you might have noticed that the episodes actually download faster than you can listen to them now, which is pretty cool. I mean, we're definitely late on that bandwagon, but through your support and all of that. We've been able to ramp up our production. And so I wanna thank everybody for that and, and helping to get more folks interested in the show and interested in programming, which is something that is just going to keep becoming more and more important. So thanks everybody and have a great week.
[01:25:01] Patrick Wheeler: Music by Eric Barndollar.
[01:25:04] Jason Gauci: Programming Throwdown is distributed under Creative Commons, Attribution ShareAlike 2.0 license. You're free to share, copy, distribute, transmit the work, to remix and adapt the work, but you must provide attribution to Patrick and I, and sharealike in kind.
[01:25:24]
