Programming Throwdown - Code Documentation with Omer Rosenbaum and Tim Post

Episode Date: June 16, 2021

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 Tim00:03:28 Omer: learning tech while in the military00:06:36 Israel Tech Challenge00:08:32 Impostor Syndrome00:12:15 Tim: the consulting career route00:18:15 Stack Overflow elected moderator00:20:59 ZFS and Btrfs 00:22:49 What is good code documentation?00:34:48 Documentation and remote work00:36:99 Good practices00:40:37 Code comments00:45:20 How to write documentation00:46:59 Signs of bad code documentation00:48:05 Swimm overview00:53:21 PyTorch documentation00:54:45 PHP documentation00:56:34 Swimm’s CLI tools01:01:16 Code documentation horror stories01:07:26 Swimm offers for open-source projects and enterprises01:13:47 Working at Swimm01:19:54 The value of remote workResources mentioned in this episode:ToolsSwimm https://swimm.io/ReiserFS https://en.wikipedia.org/wiki/ReiserFSPyTorch https://pytorch.org/docs/stable/index.htmlElectron https://www.electronjs.org/Git https://git-scm.com/Stack Overflow https://stackoverflow.com/Catch Swimm on:Twitter | Facebook | LinkedInIf 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 [e-mail] can also follow Programming Throwdown on Facebook | Apple Podcasts | Spotify | Player.FM You can also help support Programming Throwdown through our Patreon. ★ Support this podcast on Patreon ★

Hey everybody, this. Hey, everybody. This is 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. 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 how incredibly, incredibly important it is.

But I can tell you as someone 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 have no idea what's going on and it's a total rewrite. So I can tell you firsthand, it's extremely important. It's also very difficult to do kind of efficiently and to make it kind of part of your routine. So it's a great topic to really dive deep into and spend a lot of time talking about. And we're here with Omer Rosenbaum and Tim Post. Omer is a CTO of Swim, which is a company that really focuses on the documentation ecosystem. And Tim is the principal dev rel and user advocate for Swim.

So thank you both for coming on the show. I really appreciate it. It's great to be here. Thank you for having us. 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 swim? And what's that story like?

Maybe Omer, you could go first and then Tim, I'd love to hear your story as well. 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. 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 got to teach a lot and train people in various places, one of them in a program called Israel Tech Challenge. And I also got to lead a security academy by Checkpoint and to train a lot of people in many places. 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. 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. 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. And, you know, I guess, you know, as someone who, you know, I grew up over here, we're in the US where, you know, we all 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. But it's actually really interesting to hear that, you know, 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? Because that's something I think is really fascinating. Right. I think, well, military is big.

There are many different positions there. 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. 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. So there is a lot of knowledge sharing and new people coming in and going out all the time. 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? So it's three years obligatory for men and two years for women,

place it used to be so. And for most people doing technological service, it gets longer to even five, six or more years. Ah, okay. Okay. So that is definitely more time. But yeah, you're right. I mean, for let's say three years or even two years,

you know, 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 could see that's an environment where ramping up and good documentation is really, really important. That's right. Cool. And so from that, what kind of took you into the sort of private sector? So actually, it was a bit gradual for me. And I got to go to university after the military service, as happens quite frequently also in Israel. And I got into many training programs because I really liked

teaching even when I started in the army. 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. Cool. That makes sense. And so you're kind of learning and you're, 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 Swim? Did you just jump into founding a company?

Like, how did that work? Okay. So at first I was doing part-time in many training programs and one of them was called Israel Tech Challenge. It's also where I met the other three co-founders of SWIM, 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 helped them come to Israel and get incorporated with the industry in Israel.

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. 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. And they always talked to me at first about the difference from the experience of a training program, like we held at Israel Tech Challenge, where everything was organized and we handheld 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 working on tasks without a lot of guidance.

And I kind of felt that challenge through them a lot. And then together with the other co-founders of Swim, we all worked at ITC together. I also worked at other places, but they worked at ITC most of the time. So we all got to feel that challenge So we all got to feel that challenge and we all got to feel that this is something we want to tackle together at some point. Yeah, that totally makes sense. We have this saying where I work,

this is very common, called imposter syndrome. And it's the idea that you train, you train, you train, you take the interview, the interview asks you these really atomic questions like, you know, invert a binary tree or solve this dynamic programming problem. And you're on a whiteboard with very low resources, but it's such a narrow scope that with the right training, you can really nail the interview. And then all of a sudden it's like, okay, here's our, you know, 300 million line code base,

you know, for our entire company. And here's this task that's going to take six months. And so that sort of like really agoraphobic kind of experience just jars people and makes them think, well, you know, maybe I really don't belong here. I mean, maybe, you know, this is like, you know, I, you know, I'm just totally out of my league and I'm fired. And so we call this, we call this imposter syndrome and everyone goes through it. And I think a lot of the reason why that exists, at least to the degree that it does is, is because the onboarding is just leaves a lot to be desired. And so I think even, you know, 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. 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, you know, kind of experiences led you to DevRel and then to Swim? Hi, I'm Tim. I started out as more of a systems programmer. 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 back end of things. 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. But 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. Yeah. I remember when Microsoft made Internet Explorer part of Windows and I thought, oh, Netscape is in huge trouble, but Netscape was a much better product. And then there was the whole antitrust. I mean, it was a very dramatic time. It still is. I mean, we're just now seeing the resolution of bytes that we picked 25 years ago. It's so true.

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, 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. 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. 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. Wow. Interesting. So what made you go the consulting route instead of the sort of, I guess, I don't know what the other word would be like, the joining the Microsoft route, whatever you would call that. 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. 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 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 dot 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. 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 are some really shady characters in the web hosting industry even today. But a lot of it was really positive. Unfortunately, due to the type of projects I was working on in 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. 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. Yeah, I saw an article from the CTO or maybe it was the CEO of Waze. And he was talking about when they were acquired by Google. And one of the things that really surprised him was that at 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. But in big companies,

you don't really do that. 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. And 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 have to be productive. At least that's the way I see it from someone who's never done consulting. That's my thousand-foot view of it. It is. It's weird in that, well, 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 goes. In America, we have at

will employment and I think almost every state, if not every state, I'm not sure what the state of that is, no pun intended. So essentially we are consultants with benefits because our status can be terminated at any time unless you have some sort of tenure. That is beneficial both to the organization and potentially to the consultant, depending on what you want to do. You see a lot of people in consulting do this because they want to ramp up their skill set. 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? What 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. So you might spend a year here and then get the position above you at 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. 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 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, I'm not knocking vb.net, but you know, I know a lot of people struggle with that. So it does produce an interesting dynamic. One of the things that you notice foremost is how much time you spend ramping up and 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.

And it takes months. And these are productive months, but not visibly productive because you have nothing 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 been consulting with us for a month and 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. And they said, you're supposed to be able to work around that. I said, and I am by producing the documentation that I need in order to understand your code base. And that has 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.

Oh, geez. Yeah, you can really, and it's like, if you guys don't have this documentation, you're not going to be able to do anything. And I know that, and therefore, I'm going to make sure that you part amicably. 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. It was at the point where virtualization had come along. We had new processors, Intel VT technology that could, para-virtualization wasn't needed anymore.

You could just run anything you wanted to on essentially anything else. And, you know, all those years of death marches that just, I wanted to take a break from it. So at the time, I was a 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. So can you tell everyone what an elected moderator is? An elected moderator 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 MeekSTV. And the community comes and thousands of people vote

on who they want the moderators to be. And if you're lucky enough to get a slot, then you're appointed. And you're given essentially the same level of access that an employee of the company is. Oh, interesting. Cool. And then you're entrusted to be an emissary and moderator of the site.

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. 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 this opening on our community team. Why don't you come to work for us? 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 DevRel. 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 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. And I'm in a position where 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's something that I really enjoy doing. But that's in a nutshell how I got into DevRel and also hyper-fixated on documentation. Are you still into file systems? Have you been following the whole RiserFS and then ZFS going into the kernel? And are you still on top of all of that stuff? basically turn ext3 into a git repo and you know rollback files from snapshots in the past or

whatever you wanted to do and then after that i started working on some cluster file systems but i haven't been up to speed i remember what happened with riser fs that was just tragic i did not know about zfs going into the kernel that's something i need to check out yeah actually and there there is a like a bitrod fs or brt fs something like that. That one, they're both of them. ZFS and BitRotFS have copy on write. 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.

So every day it made a, you know, 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. And then, and then if you modify either one of those references, then it's smart enough to actually 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 really efficiently. 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 implemented it. Oh, interesting. I didn't know that. I'm working in web hosting, and we have all of these, you know, this whole farm of Pentium 4 HDs on Baker's 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, I wanted to hopefully build an offering around that. So 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 so that was basically it as far as how I really embraced DevRel is, you know, not

so much just purely one or the other. I'm, you know, sort of both. 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. I mean, and actually independent of age, there's folks who are switching careers. And so for someone who's just getting into it, you know, what is code documentation? Like maybe what is good code

documentation and why should people do it? Good code documentation is whatever, as you said early, very early, early on, whatever helps you learn without triggering the minimum reactions that your body has to stress is the best. 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. It 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. People learn differently. At any given point, if you hire 10 developers, people come to

you and they're onboarding and they're really vulnerable at that stage. They're into something new. 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 at 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. 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. 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. 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. And additionally, documentation gets a really bad connotation because people are thinking, yeah, that's that 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. 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 a whole lot more to say about that sure so i think first good documentation helps you understand what's important jason 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.

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. 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. It only gives you the sense of what currently exists in the code and not what led to it. For example, the motivation, all the decisions that developers have made throughout the time. So basically good documentation helps you get really fast into understanding everything you need to know in order to make meaningful contributions. 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, you know, self-healing system is

really underrated, really important. I'm thinking about, you know, I have two kids, the younger one is just getting all four of his molars in now. And so he's a bit of a terror. But I remember that with the older one, as most first-time parents do, we tried to plan everything out. And then sure enough, nothing actually goes to plan. And what we learned was that really, when you're raising kids or when you're 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 what's really important.

And so people go into, you know, testing and code documentation, trying to come up with rules. Like I want 80% test coverage, or I want, you know, every function in this folder to be documented. 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 you have some failure in your code base, that should turn into a test, right? So like whatever you had to fix to fix that failure should be part of a test. And similarly, when someone comes to you and they say, you know, 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 need to heal from that. And so, yeah, that is extremely important. It's really about setting up the right adaptive processes. I agree. I also think that when you read through documentation that has gone out of date, because in most cases, documentation doesn't leave in parallel with the 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 task, that make sure that the documentation still matches the current state of the code as it evolves. Even if the documentation isn't fully updated, it's really helpful for me to say if I'm onboarding something or to doing something, because 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. 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? You know, 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. 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.

And we talk about onboarding as if 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 those code bases are going to change drastically almost every single day. 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.

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 it interacts 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 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. 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 gigabyte in order to run. And you tried debugging it on your laptop and you're wondering why it won't work. And you waste, you know, 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 need to debug that. Having that debugging guide handy

when I'm first going, just some breadcrumbs for that would be huge. And this is part of what I call the tacit knowledge, 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 the documentation works, if you can imagine, you just get the nozzle and you sort of squirt it on the roof of the car and you hope the gas soaks in where it needs to go somewhere. That is actually the song and dance that we make our fellow programmers do. And we really need to stop doing that because it's not fair to them and it wastes a lot of time. 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? Yeah. And someone could have stopped you from pouring gas all over your car. I mean, it's not only a waste of time, but it's also for the new person, it feels as if you 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 what we should be doing to each other. It's a really good example of that. And 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 actually has to happen. 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. Yeah, that all makes a ton of sense. So I think we talked a lot about what good documentation is and in terms of why, you know, one of the biggest reason is what we all touched on that, you know, even if you write the code and someone else, assuming you have some type of peer review process, if someone else is peer reviewing it right off the bat, twice as many people have read the code, right?

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 have 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. And the same is true for documentation. And so this helps a lot of the insecurity and the stress that people feel when they're onboarding. Another thing which is, I think, going to become more and more important is that documentation sets up contracts between or among engineers. And 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, your function, can you also make it accept floats? Because I have some fractions I

need to pass in. You can't do that anymore. 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 know, set up contracts and documentation could be a really good way to do that. teams that are distributed, set up contracts and documentation could be a really good way to do that. It definitely can be. Absolutely can be. What's even worse in 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. 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, you know, in Brazil or wherever aren't part of the conversation. And that, that can really happen in a lot of organizations, unless you're very deliberate about it. Cool. 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, you know, and is it something where it's totally in the code? Like how do you reconcile your code versus

a wiki versus your 10 other media? You know, what are good practices there? 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 uh like well as soon as the thing that you're working on starts looking you know it's taken a similar shape a few times you've solidified the code you solidified the behavior you've got you know 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 writing 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. If I write that documentation in two days, when I released 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. And it is going to be thus 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. 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 your documentation about stuff that you don't really remember. Yep. I have another rule that I follow, which is if I see something that an elementary coder wouldn't understand that I asked that there's some documentation next to that. So for example, you know, we write most mostly in Python and in Python, there's this thing you can do. There are these, I forgot what the name of it is. It's the functions that have the underscores in the beginning. There's a term for all of those.

The most common one is underscore, underscore, init, right? But there's other ones. In this case, it's underscore, underscore, get atter. And you can use this. So if you have a object in Python, like foo, you can actually call like foo.x, foo.y, foo.z, even if these aren't members of your class. And if they're missing, it will call this function. And so you could effectively do foo.anything and it will actually, it won't, it will, it will do something. It will go into that function and something will happen. And so- Overloading. Yeah. Yeah. And so I think it's all like magic methods or something, that whole category, like underscore, underscore, EQ

and all of that. But someone used that and I just said, hey, can we just document why we're using that? Because it's going to add cognitive overhead, right? And so in this case, it had to do with overloading a class that we didn't own. And so there's a good reason to do it. But anytime you have to do something that is, you know, 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. And so I've had cases where right when the code went in, there's some comment saying, you know, yeah, you know, 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, you know, why am I dividing by 67,000?

Like it doesn't be in a function called square root, right? Right, exactly. And so, yeah, I think some code, and you'll know right away, some code needs to be documented, you know, zero day. And then to your point, as soon as you start kind of having the whole idea, then you could really kind of document everything else too.

You just said trick something that I think is really good to bring to light. Coming back to sort of the imposter syndrome thing, a lot of engineers that I know would not ask questions about that. They would just say, oh, 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 hit it. Right. And I think, Jason, that's a great example of where inline comments, comments in your code, are actually the right way to go. You have a specific line 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 inline what's going on. This is the kind of things that you want to document inline within the code. I think for other cases, like flows between different code files, between different functions, or nowadays between different repositories,

what you want to do is document not within the code itself, but in external documents 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 text

and then it's also hard for them to start writing because they don't even know where to start. And also it tends to become not as practical because as a consumer of that document, I just read a lot of text 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. So I would want to read a document and feel like Tim is standing 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. 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. 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. 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 wall of prose

back to the code base. And then on the other end of the spectrum, if someone gets their hands on Sphinx or one of these tools and they auto-generate 10,000 HTML files, but because they're auto-generated and 99.9% of the code isn't documented, you end up with just all this auto-generated text that is just agoraphobic. Like no one's going to read any of that. And it also kind of people don't. Right. And it's without context.

Yeah. And people don't document it because it's now so big. And even if I documented it, who's going to know what's documented? And so that's two ways in which I've seen this fail. With the co-comments, you should absolutely be doing that. You should be doing that for the person that you you should absolutely be doing that. 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 code itself. But those comments are sort of

like rungs on the ladder, and they need something to stand on. They need the higher level narrative to guide people through that. 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 are the code paths I need to do that? All of the great code document, you know, if everything is document and comments there, that's awesome. But people tend to start their discovery on an endeavor. 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. If you need to show people how to, what dependencies do they need to inject when they ins instantiate 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 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. 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. Yeah, that totally makes sense. So how do people go about doing that? I mean, we talked about kind of these two extremes, but if you wanted something with better balance, so if you want to be able to write a story, but have that story, you know, reference the code, 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? 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. The easiest way would be to copy paste snippets of the code to your document and just talk about that. The downside to that, and we can talk about this later, is that it may indeed become out of sync quite quickly.

But it does ease up the process of explaining a flow. You start by selecting the code you want to talk about, copy-pasting it to a document, and then from that document, you describe the flow itself. Also, by starting with the 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 in the broader scope of a full flow. And it 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. One of the biggest telltale signs of not having great documentation is not seeing code reused when it should be. It means that people just aren't 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. Oh, that is really interesting. Yeah, that's a really fascinating metric. Yeah, I mean,

there's a whole tangent on what are good sort of metrics that you should capture when running a software team. But yeah, 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. It's a balance to it. Depends on your setting and 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 take the context of everything else into place. It's one of the things that you should definitely watch out for. Cool. That makes sense. So let's dive into Swim 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 Swim help with these things? So Swim encourages doing exactly what we just described, and that is creating code couple documentation. And by that, again, I mean documents that actually include references to the code itself. So when you create documentation with Swim, we help you include those code snippets or specific references to functions or to file path 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. What we do at Swim is we track the changes to the code base as part of your CI or other hooks, like a Git hook. 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. 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're 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. 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 visit

on your intranet, and you can get a hyperlink to a file or even a specific range of lines in a file. And so you might say, well, if I'm going to build this documentation, I would add these links to line 90 to 100. I'm going to reference that block of code as I'm writing my documentation. This is the broader documentation. But then as you said, let's say someone adds a new function and they add it in line 80. Now your function got pushed down maybe 100 lines. And so if you don't update that link, it all of that, which is almost impossible if you're working with a large team, right? I mean, it's very hard for someone to know that you've put a hyperlink below them and any line they add will break that link. So Swim takes care of a lot of that. like an operational transform, in those cases, you can kind of alert people and say,

yeah, this function reference is totally gone, or it's someone completely rewrote it, and now it's 100 lines. And so you should probably take a look at it again. Correct. So one part is the bookkeeping, as you named it. So that could be different line numbers, it could be a rename, or just moving the file somewhere else. 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 don't know, renamed one variable or added 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. So also in these cases, we suggest the changes that should be made. For example, now you need to include this edge case

as well. But yeah, in cases where the code really changed drastically, it would just tell you, please pause now and reconsider your documentation and make it up to date again. 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 IDE, for example, we can show you, wait, this function here has a document describing it. And as opposed to inline comments, this document perhaps explains how this function takes a

role in a broader flow. 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. Yeah, that makes sense. I would actually love to ask you both of good examples of

this on the web. But one example that I personally feel is really good is the PyTorch documentation. You know, 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 actually browse the entire source tree with comments. And there's also auto-generated markdown HTML files for every file. But then they have these narratives like, here's how automatic differentiation works. Here's how sparse tensors work, right? In those narratives, they're linking back to either the API or the source code. I don't remember exactly how that works, but they have both and they're both really important. And actually, I love the idea you just mentioned. I mean, it would be great if while, you know, let's say you choose an autograd system, you choose Atom or AdaDelta or one of these

things, and you're in Visual Studio Code and you type torch.optim.atom, right then and there, maybe they could pop up a little box. In addition to the box that tells you the arguments, which you might already know, I mean, there could be a little box saying, here's how automatic differentiation works and gives you kind of that more high-level information that's really important. I've seen that 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. 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 which one your team is likely to use.

And PHP CodeIgniter, as well as Laravel and Symfony, can do deep dives into and say, look, this is to overcome a language feature or something that isn't implemented in the language yet. Or this is because of a way that the language works, that we're implementing it this way. And 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 really good examples of documentation.

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 goes a lot faster. But at the same time, we are giving up a lot of documentation that was already written for us about the stack that we're using. And I don't think that the true cost of that is conceptualized by CTOs and CIOs more than it should be. Yeah, that makes sense. I think maybe post-hoc, they're looking and saying, why did our productivity go down the drain?

What they should be doing is being defensive and kind of looking ahead and saying, having the right metrics as we talked about, saying, okay, well, why is the health of our documentation going down? And that would allow you to be proactive. My favorite features of Swim 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. 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 actually run if you're doing a full build. And the answer to that was anywhere between five minutes and hours for that to run. So I think some teams might not be all that eager to update it before you even do the PR at that process. When the lints run and spaces get converted into tabs, as it should be. I don't want to start that war on this podcast, though. 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, it was like heated discussion about it. 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.

But anyway, one of the things that I like about just the design of Swim is it's all of the little tools that you need to couple all this stuff together in the ways that we're talking about. 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 new versions and stuff like that. Swim just does it in a way that doesn't present you with the least resistance to actually keeping it up to date. I think, Jason, beforehand, you mentioned that when something goes wrong nowadays, we add a 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. 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 tests in that manner. Yeah, it totally makes sense. I think having the right metrics and getting that instantaneous feedback is so important for building the right incentives. And I think for tests, 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. And most of the things I work on 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 because you just see that result. And so getting documentation into that flywheel

is super powerful. Right. I think it's also a means of gamification in some means. And you get like 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. So for example, if you're able to see that this module

or this folder or this file has corresponding documentation and this file 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. 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 lives 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. 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. Yeah, that's a good call. That seems like a nightmare scenario, right? 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 edit stuff in that folder. What is actually a bit of a sidetrack here, do you have any horror stories, documentation or just code health horror stories that you'd

want to share that the audience would get a kick out of. I have an interesting story about some jellyfish. Sure, let's hear it. So I was working in embedded systems. It's one of my hobbies. And occasionally I do some consulting to help people do it. So is this like Arduino type stuff? Arduino, gumsticks, Raspberry Pis. And then there's also some industrial single board computers out there, different varying architectures.

Cool, cool. Very nice. Getting operating systems into small places and you've got that four megabyte ceiling is really, it reminds me of poking away on my old 386. So it's a lot of fun to do sometimes. Yeah, yeah. And there was a power company in Asia that had a problem with jellyfish. And the problem was the freshwater 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 combat that so that if there were like a whole school of fish going by, the plant could not take in as much water right then and then it wouldn't be so disruptive to the environment. Systems like that, that you write, you know, and you think, okay, this is going to be like a, a temporary thing, you know, because the ocean currents are always changing and stuff like that turns out not to be. And then it turns out that, you know, pillars are built on top of something

really, really rickety that you implemented a long time ago as a quick workaround. And that tends to happen all the time in software. But in particular, 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.

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 anymore. So luckily they were able to reach me to find out why seawater wasn't getting pulled in

in that part of the control loop. But that was just one of the interesting things where you can, 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. Yeah, that's a really good call out. Patrick and I worked, they called it the advanced research lab at another company. And that's how we originally met many years ago, I think what, I don't know, 13 years ago or something now. So at the time, neural networks were a pariah.

Like if you believed in neural networks, it was almost impossible to graduate. You know, Marvin Minsky, all these people have 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 get this up and running. And now fast forward, you know, I was talking to, you know, I went back to the East Coast was ever going to amount to anything. And here we are in this lab trying to get this up and running. 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, they're still using some of the code we 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 just felt like, well, you know, here's this throwaway idea that no one believes in.

And so you just never, ever know. And it's so important to have some type of way to kind of continue that because it could end up being, you could end up saving the jellyfish ecosystem or end up writing something a lot of people use a long time later. I've talked to people that implemented things that like the Palm Pilot, if you remember those, the Palm V with that LCD and the stylus. And there are people to this day that are using code that he wrote for Palm V hot sync to Linux, which has not been supported by Palm for probably 20 years now. So yeah, it's just amazing 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, you know, code that you wrote when you were a very

different person ends up, you know, saving someone a lot of time. It's great. 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 were prioritized as the most important and urgent to be sent and we couldn't receive them. 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. Oh, no. Yeah, there was no documentation helping us there. And yeah, it actually got a lot of important messages to get lost in the way. Yeah, that is definitely a documentation nightmare. So going to Swim,

so imagine there's sort of two ends of the spectrum. On one end, there is somebody who is just starting out, you know, 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 public repository. And then on the other end of the spectrum, there are the folks who are in an industry, you know, and they, you know, 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. And so what can Swim offer these two kind of audiences? So Swim 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 Swim 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 sure. 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 would be amazed, especially if you're a PhD student or if you're doing your senior design project, if it's something that has legs, right? You know, my PhD project still gets a lot of stars on GitHub and that code is absolutely atrocious. So, you know, 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. Jumping into the, into the enterprise, how does that work? Like if someone wants to use Swim, but you know, they, they have very strict kind of IP rules or, or, you know, 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 or how does that work? It's an app that's written in Electron. So it's highly portable. And the Swim 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. On our side, we don't really get anything about your code or anything like that. All we get is some relational mappings so that we know that this playlist of documentation is tied to this repository. But it's all hashes on our side,

so they don't have to worry about that. And it's currently very beta right now, but 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're trying very hard to support. 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, like the things, the artifacts for Swim are in the repository, then you don't also need some centralized service that's storing a bunch of information.

So each person runs the Swim desktop app and effectively it's communicating through the commits to the Git repository. Did I get that right? To a certain extent, yes. What Swim will do is it'll understand a concept of teams and which repositories are tied to which teams. So Swim will know if you have all of the repositories installed on your local machine because it will be able to find them.

Or it will tell you, hey, you need 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 site so that you can get it. And Swim 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. Likewise, if you're working on documentation in 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 branch.

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 Swaim handles, but something that you handle on your own, for example, by using GitHub. Yeah, totally makes sense. And so, okay, that makes sense. So if someone is working for enterprise company, they want to try out Swim, how would they go about doing that? Is it something where they, on their own, you know, is there a trial or 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 kind of lobby to start using it?

So currently we are in beta. So you reach out to us on the website, but you're always welcome to start working on your own for free and also for a 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 Swim before swiping a credit card or something like that. So the beginning is for free and we are also very eager to help you getting started and seeing how people use Swim and what kind of great documentation they create and then consume using Swim.

Cool. That makes sense. So yeah, I think this is amazing. Everyone should definitely check this out. We'll have links to the show in the show notes and all of that. And the show notes, for people who don't know, are linked from usually, depending on your podcast player, there's almost always some kind of details section. And we always put a link to the show notes there. Cool. So let's jump into Swim a little bit as a company. So how old is Swim and how is Swim sort of set up? Is it a distributed company? What's sort of that whole story like?

So Swim 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 Swim and during COVID-19. 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 Swim

to use for onboarding our few first hires. 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. Cool. And so what is a typical day like for an engineer at Swim? What do you use to communicate? And what is something that you think would be kind of interesting and makes your company

kind of stand out from a kind of day-to-day perspective? 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 Swim. Oh, that makes sense. Yeah. 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. What we also have, and I think is quite cool in Swim, straight from the beginning, we have a ritual we call Swiminars.

So it's like a seminar, but a Swiminar. 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 swim. 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. What I also think is cool at Swim 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 Swim who are not open source projects because we don't have access to their code, but we always have examples of how we use it internally. Cool. Yeah, that makes sense. How do you navigate the time zone difference? So I believe, I want to, so my family's in Italy and Israel, correct me if I'm wrong, I'm terrible at geography, but Israel is, yeah, Israel is definitely east of Italy and Italy is eight hours. So, so I don't know where Tim is in the U S but I mean, you're looking at potentially

like a 10 hour time zone gap. Right. And so how do you, how do you handle that? Seven hours. It's yeah, it's, 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. Oh, wow. I've been remoting.

I mean, remoting is just something that I do. Stack Overflow was a remote-first company, still is. And when I was working there, I was 13 hours ahead of everybody. I was living in Metro Manila at the time. Oh, interesting. You have to be very deliberate about it and you have to make sure that you make sure you're in the places where the right information bounces off of you, no matter kind of what time you get to it. But the coordination doesn't, it doesn't break it. It's easy to do. Occasionally I might have to get up at like an hour earlier to make an earlier meeting, but the coverage as far as

the customers are concerned is almost around the coverage, as far as the customers are concerned, is almost around the clock, which is great. It actually is around the clock, which is fantastic for them. So it's not too bad. 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. 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. 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 then 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. Yeah, that makes a ton of sense. Our ritual is on Friday evening, we typically break the bill. And then we come back on Monday morning. That seems to be the ritual that we've been following for the past few weeks.

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. And the challenge there is, you know, when you're working with a whole bunch of different teams, the odds that you and someone else, or maybe put it 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, you know, when we get back to normal or whatever that is, the new normal, the odds 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 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. No, 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 when everything is essentially just on fire and horrible, we can all agree to that.

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 kids. All of the stuff that working remotely provides has shown, I think, significant value during the pandemic. That value, I think, has eclipsed comp for companies that will not offer full remote arrangements for their employees. 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 to be able to do 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. 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 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. 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 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. Yeah, I totally agree. 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 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 a.m. 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 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 headspace now. 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 like it really closes the loop on a lot of this and kind of makes it a lot easier. So I really appreciate you, Omer and Tim, both coming on the show and talking and sharing your experiences. Oh, it was great to be here. Yeah. Thanks so much for having us. 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. So you might've 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 want to thank everybody for that 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. Music by Eric Barndaller Programming Throwdown is distributed under a Creative Commons Attribution Sharealike 2.0 license. You're free to share, copy, distribute, transmit the work, to remix, adapt the work, but you must provide an attribution to Patrick and I and sharealike in kind.