WEBVTT 1 00:00:04.639 --> 00:00:08.599 Hey, welcome back to another episode of the Ruby Rokes podcast. This week 2 00:00:08.599 --> 00:00:13.759 on our panel we have Valentino Stole and now I'm Charles Maxwett from top End 3 00:00:13.800 --> 00:00:19.559 Dev's. We have a special guest this week and that is swat. Do 4 00:00:19.600 --> 00:00:23.960 you want to just tell us you are? And sure? Sure? So 5 00:00:25.359 --> 00:00:29.600 I'm back at the engineer at Evil Mustians and I really love working with all 6 00:00:29.640 --> 00:00:35.280 the exciting technologies using Ruby eggs, like to make Ruby look like Golang. 7 00:00:35.320 --> 00:00:41.960 For example, writing barsers running Ruby was in browser with Ron Ruby, Don 8 00:00:42.079 --> 00:00:47.759 Dev and Charles. You decided to bring me here to talk about API documentation, 9 00:00:47.920 --> 00:00:53.159 right that? Yeah, that's my favorite topic. I'm every week on 10 00:00:53.240 --> 00:00:56.439 the show. I'm like, we're not talking about API documentation. Why am 11 00:00:56.479 --> 00:01:00.799 I here? Let's fix that? Yeah, let's let's do it. So 12 00:01:02.000 --> 00:01:06.599 I have to say it seems like documentation is the thing that everybody just kicks 13 00:01:06.640 --> 00:01:11.480 the can down the road with. Right. I'm also going to point out 14 00:01:11.079 --> 00:01:18.159 so not this contract that I'm on. The contract before I was working on 15 00:01:18.200 --> 00:01:22.239 some API. No, it was two contracts. Anyway, I was working 16 00:01:22.280 --> 00:01:25.680 on basically integrations between two APIs. Right, It's like, hey, get 17 00:01:25.719 --> 00:01:27.079 the information out of here and sync it up with the information over here. 18 00:01:27.879 --> 00:01:36.640 And I have to say, API documentation is a concept that some of these 19 00:01:36.640 --> 00:01:38.799 folks could have worked on. Let me just put it that way. The 20 00:01:38.799 --> 00:01:42.079 people who documented the APIs, it's like it's like, okay, yeah, 21 00:01:42.120 --> 00:01:48.519 you're telling me all these fields, but you know, it doesn't actually tell 22 00:01:48.519 --> 00:01:49.560 me how to use it, right, And so I wind up trial and 23 00:01:49.680 --> 00:01:56.400 erroring my way through sending them a date or a string or you know the 24 00:01:56.439 --> 00:02:00.799 structure of the data I have to send back. So yeah, so how 25 00:02:00.799 --> 00:02:06.519 do we do it better? Yeah? So I was in the same position, 26 00:02:06.719 --> 00:02:10.120 and I was one that did that to you, not not to you, 27 00:02:10.280 --> 00:02:15.479 but you know, two different developers with the poor documentation. So if 28 00:02:15.520 --> 00:02:23.560 you yeah partially, So yeah, let me just tell you tiny story that 29 00:02:23.680 --> 00:02:28.280 covers up like the whole my career, like the past ten years, and 30 00:02:28.319 --> 00:02:35.960 I'm doing API APIs. So I started my rugby career in small healthcare startup 31 00:02:36.719 --> 00:02:43.080 and we had a simple rails API only application on the back end and two 32 00:02:43.159 --> 00:02:47.840 native mobile apps, so only three of us, no seniors, no rules, 33 00:02:47.879 --> 00:02:57.599 no documentation, and everything went pretty fine until we started developing fairly complex 34 00:02:57.680 --> 00:03:04.080 features, and quite soon we went to the developing features. Spread across three 35 00:03:04.120 --> 00:03:12.759 different platforms without any API documentation is quite painful. So we started documenting our 36 00:03:12.840 --> 00:03:21.039 API using a new and heap app called postmon, so we might use that, 37 00:03:20.479 --> 00:03:25.080 and that saved my life on the scenario I was talking about, because 38 00:03:25.120 --> 00:03:29.560 I could rapidly go this, no, this, no, this, no 39 00:03:29.719 --> 00:03:32.840 this no, hey it worked, Oh it kind of worked this anyway. 40 00:03:34.759 --> 00:03:38.159 Yeah, yeah, basically that's what we did. So you can save those 41 00:03:39.560 --> 00:03:46.680 actual like tries and reuse them later. So that was our documentation in the 42 00:03:47.000 --> 00:03:52.759 at the moment, and it went again pretty fine until I forgot to update 43 00:03:52.800 --> 00:03:59.439 it too many times so and our personal collection become constantly stale. And with 44 00:03:59.680 --> 00:04:06.639 that we discovered arthwag, and artwag is a gem that extends Arspec with a 45 00:04:06.680 --> 00:04:15.360 special DSL and uses that to generate and open API documents, which then turns 46 00:04:15.400 --> 00:04:24.560 into beautiful live documentation. And that's basically my dream came true because you know, 47 00:04:25.759 --> 00:04:31.639 we generated something like postma collection right from our Arspec tests. That's a 48 00:04:31.680 --> 00:04:36.519 miracle, and we don't need to think about API docs. They're just there 49 00:04:36.600 --> 00:04:45.399 and always up to date. That's cool. So the resulting development process it 50 00:04:45.560 --> 00:04:49.319 looked like this. So I developed a Vizero version of a new API feature 51 00:04:49.680 --> 00:04:56.360 that we need. I tested that with artswag generated documentation and passed that to 52 00:04:56.959 --> 00:05:03.759 mobile debs. Then they use the documentation and they implement their own interfaces, 53 00:05:03.800 --> 00:05:09.720 and sometimes they asked me to fix my API, and since it's rails, 54 00:05:09.759 --> 00:05:15.360 I do that pretty like quickly, right they need to rewrite tests when I 55 00:05:15.439 --> 00:05:21.240 do those changes. Was kind of irritating, but still it worked pretty fine 56 00:05:23.800 --> 00:05:30.519 until the time we decided to add a medication reminders feature to our app. 57 00:05:31.199 --> 00:05:38.160 To support that, I designed a model that added to fields like start date 58 00:05:38.439 --> 00:05:46.160 and end date, and I made end date noble since for cases when reminders 59 00:05:46.199 --> 00:05:53.439 should never stop, because you know, medications. So with that, weeks 60 00:05:53.519 --> 00:05:59.279 later, I'm testing the resulting application, the mobile application, and what I'm 61 00:05:59.319 --> 00:06:02.959 seeing is a reminder with the end date in the year to like four thousand 62 00:06:03.040 --> 00:06:10.399 and one, which is kind of strange to see that and fast, Yeah, 63 00:06:10.439 --> 00:06:15.199 apparently I was developer. Decided to mark those infinite reminders with a day 64 00:06:15.480 --> 00:06:24.639 distant feature like distant future, and that thing serializes to the year four thousand 65 00:06:24.639 --> 00:06:30.360 and one. Wow. Okay, since my biln deavs in my team they 66 00:06:30.399 --> 00:06:36.600 were better team players than me. They discussed that decision actually, and Android 67 00:06:36.639 --> 00:06:42.639 developer did the same. But in Java cyralized version become the year nineteen ninety 68 00:06:42.759 --> 00:06:50.040 nine. Oh wow. So that was a sign that something went completely wrong 69 00:06:50.079 --> 00:06:55.759 with our workflow, right, And the problem is we had the documentation in 70 00:06:55.800 --> 00:07:00.360 place, and the end date was marked as new in that documentation. So 71 00:07:01.240 --> 00:07:06.240 and if you think about that, it's really logical to use like now for 72 00:07:06.800 --> 00:07:12.560 end date that is unknown at the moment, because it can be anything that 73 00:07:12.879 --> 00:07:19.199 user can add like date there and stop taking those medications like tomorrow or in 74 00:07:19.240 --> 00:07:25.439 two weeks or in two years whatever. So the now is like it's like 75 00:07:25.519 --> 00:07:30.279 by the book, like it's like the description of Noll. And yet Mobile 76 00:07:30.360 --> 00:07:40.680 Deaths decided to do that horrible wrong thing. So but if you think about 77 00:07:40.680 --> 00:07:45.480 that, actually it was me who was wrong because my attitude towards the documentation 78 00:07:45.920 --> 00:07:50.480 was completely wrong. I thought about that as a like artifact, and I 79 00:07:50.519 --> 00:07:58.639 didn't write like proper description to explain why the end date is noble. And 80 00:07:58.720 --> 00:08:01.439 we never discussed that case with the team, or maybe we did, but 81 00:08:01.600 --> 00:08:07.000 we lost that somewhere in the selector. So aarspect didn't help me to become 82 00:08:07.040 --> 00:08:13.240 a better developer. Thankfully, about the same time, I bumped into talk 83 00:08:13.319 --> 00:08:22.160 about the competation first approach from Reelsch twenty eighteen by Aeriel Kaplan, And after 84 00:08:22.240 --> 00:08:28.639 that I finally realized that the commutation is actually the core of my API and 85 00:08:28.800 --> 00:08:35.519 not just the leftover. So now I, honestly I can't imagine developing APIs 86 00:08:35.600 --> 00:08:41.679 in the other way. So let's take in this, like, what do 87 00:08:41.759 --> 00:08:46.039 you mean by documentation first? Like, I know, you know, folks 88 00:08:46.080 --> 00:08:50.759 can listen to Aeriel's talk, you know, after this, because it is 89 00:08:50.759 --> 00:08:52.840 pretty great, But can you sum up just like, what do you mean 90 00:08:52.879 --> 00:09:01.000 by documentation first? Sure? So with the commutation first, you start your 91 00:09:01.080 --> 00:09:07.720 work by writing the specification for the resulting API. And that might sound like 92 00:09:09.200 --> 00:09:15.240 the most boring thing in the world, but actually that's what the best programmers 93 00:09:15.360 --> 00:09:20.679 do when they design their code. Matz doesn't start with the implementation of a 94 00:09:20.759 --> 00:09:26.080 new feature for the language. He discusses the interface first, and in that 95 00:09:26.200 --> 00:09:33.720 discussion, that discussion itself, it might take much more time and effort than 96 00:09:33.759 --> 00:09:39.080 the implementation itself, And probably that's why we'll offer Ruby, and maybe that's 97 00:09:39.399 --> 00:09:46.879 why we have next to none breaking changes in our language. So like another 98 00:09:46.919 --> 00:09:54.080 example, like imagine silently preparing a giant PR to bring something cool to your 99 00:09:54.159 --> 00:10:01.120 project, or say to open source project and say you prepared the PR for 100 00:10:01.600 --> 00:10:07.879 Rail's active model, like bringing something really cool and giant and awesome, and 101 00:10:09.080 --> 00:10:13.120 you opened it and you've got a review from someone from the core team and 102 00:10:13.159 --> 00:10:18.639 they say that, actually, you know, the resulting interface, it's not 103 00:10:18.759 --> 00:10:24.960 in line with the Rail standards, Like we have all those different ideas already 104 00:10:24.039 --> 00:10:31.360 here and there, and they have like all the examples and clear action points 105 00:10:31.360 --> 00:10:37.240 for you. So it's not a rude no, it's an actional thing. 106 00:10:37.679 --> 00:10:41.679 But in the result, to get your PR accepted, you need to rework 107 00:10:41.759 --> 00:10:46.240 everything from the scratch. And I don't know, do you feel the pain 108 00:10:46.360 --> 00:10:52.559 right now? Because I definitely do what would be better to create an issue 109 00:10:52.559 --> 00:11:00.919 and discuss an interface first rate. That's basically the documentation first approach. So 110 00:11:01.080 --> 00:11:05.200 let's let's give another example with an API, since we were talking about APIs. 111 00:11:05.879 --> 00:11:09.480 So you are working on a new feature. You designed the models like 112 00:11:09.600 --> 00:11:15.399 services, commands, form objects, whatever you use, and you tested all 113 00:11:15.399 --> 00:11:18.240 of that, of course, and you pass the result to your team and 114 00:11:18.679 --> 00:11:24.559 Apparently you're like pagination, filtering, design whatever it went out of think with 115 00:11:26.000 --> 00:11:30.440 what front end needs, and for some reasons, they are locked to use 116 00:11:30.440 --> 00:11:35.600 that specific format because of framework or vend or whatever. So it's your fault 117 00:11:35.639 --> 00:11:43.519 and you must to drop everything and all that beautiful, well tested, perfectly 118 00:11:43.559 --> 00:11:46.480 designed, re usable code that you did. You just need to remove that 119 00:11:46.559 --> 00:11:54.600 and start from the scratch. So maybe, like I know how many listeners 120 00:11:56.200 --> 00:12:03.639 screaming in again you right now that that would never happen to them. Like, 121 00:12:05.440 --> 00:12:09.240 but if there is no process, you might discuss oagination, but forget 122 00:12:09.279 --> 00:12:15.360 about filtering or mids the fact that front end needs that specific interface. And 123 00:12:15.399 --> 00:12:20.519 so we are all just humans or martians and we need processes to guide us. 124 00:12:20.639 --> 00:12:28.879 Right. Another idea is a no one ever complained about my dogs, 125 00:12:28.200 --> 00:12:35.279 so they are good. Probably, Charles, you had your your story about 126 00:12:35.320 --> 00:12:41.720 documentation. Have you ever told the other side that their dogs are bad? 127 00:12:41.960 --> 00:12:48.720 Yeah? Cool? So in my situation, I worked in a company with 128 00:12:48.759 --> 00:12:54.279 one hundred micro services and like four or five different service SID languages. In 129 00:12:54.320 --> 00:12:58.399 that structure, you're always a consumer and a provider of an API, right, 130 00:12:58.840 --> 00:13:07.279 So I saw what happening when someone uses those OUTO generated dogs with like 131 00:13:07.519 --> 00:13:11.840 this idea that it's a simple artified and it was just unusable, as you 132 00:13:11.879 --> 00:13:18.159 said, like it was just a list of function names instead of human readable 133 00:13:18.879 --> 00:13:26.240 descriptions, and it was just a silent list of hopefully all attributes and that's 134 00:13:26.279 --> 00:13:31.879 not enough to work on. Uh yeah, in yeah, I just want 135 00:13:31.919 --> 00:13:33.039 to chime in there. I mean, this is the problem I have with 136 00:13:33.080 --> 00:13:39.240 like our doc as well and things like that, is like you've got some 137 00:13:39.279 --> 00:13:45.320 comment or maybe it'll actually scan the code, it's just yeah, you don't 138 00:13:45.320 --> 00:13:48.279 get the whole story, right. It's like, Okay, I've got a 139 00:13:48.320 --> 00:13:52.240 list of parameters and maybe an endpoint to hit or something, but it doesn't 140 00:13:52.240 --> 00:13:58.639 give me enough to know how it's meant to be used. True. True. 141 00:13:58.240 --> 00:14:03.639 So in case, when it was Python on JavaScript on the other side, 142 00:14:03.679 --> 00:14:09.159 I was able to just open the code and read it instead of documentation 143 00:14:09.240 --> 00:14:13.600 and it was fine. But when it was Java or something else, I 144 00:14:13.759 --> 00:14:20.840 just started deeming developers because it's impossible to work with So voluntina. I know 145 00:14:20.960 --> 00:14:24.960 you use arspec, how do you use that? So do you document your 146 00:14:26.200 --> 00:14:35.120 your API? Do you use that? You know DSL extensively some teams use 147 00:14:35.159 --> 00:14:39.840 it more than others. But yeah, it's use that a you know, 148 00:14:39.320 --> 00:14:46.639 URSPEC focused realm where the specs will basically you know, there's another side of 149 00:14:46.639 --> 00:14:54.120 this where documentation first is a nice API first you know design principle. Another 150 00:14:54.000 --> 00:14:58.840 realm of people also think test driven is also a good way of also documenting 151 00:14:58.879 --> 00:15:05.799 the code and processes, which may be not the best case for all API 152 00:15:05.879 --> 00:15:11.639 design. Ah, but yeah, it's definitely more test focused than it is 153 00:15:13.279 --> 00:15:20.639 documentation for cool cool cool. So actually, you I met people who do 154 00:15:20.960 --> 00:15:28.039 artsqac. Do you use artsquac extensibly? Like they you can write beautiful documentation 155 00:15:28.159 --> 00:15:33.559 with arsuac, But there is other side, like do you, like, 156 00:15:33.960 --> 00:15:37.720 can you ask your front end team to write those artsquac tests for you? 157 00:15:39.399 --> 00:15:41.600 Or maybe in that case when you work in the company with a lot of 158 00:15:41.639 --> 00:15:48.240 backends tacks, are you ready for some parcel tongue developer to write your tests 159 00:15:48.320 --> 00:15:54.080 for you? I'm sorry, but I'm not, so let's use yama instead. 160 00:15:56.159 --> 00:16:00.960 So yeah, the commntion docummuentation first, or you can call it specification 161 00:16:02.120 --> 00:16:06.960 first, scheme first, design first, whatever, it's all about that. 162 00:16:07.080 --> 00:16:12.159 It's all about bringing the process to your workflow. It will not work if 163 00:16:12.200 --> 00:16:18.519 you just silently write a giant yano first and then write the implementation all by 164 00:16:18.559 --> 00:16:23.480 yourself. There is no communication. So it might be still better because it 165 00:16:23.600 --> 00:16:30.399 will work Like TDD, you think about interface first and then implement it. 166 00:16:30.720 --> 00:16:37.960 But still it's all about communication and your documentation. It must be the central 167 00:16:38.000 --> 00:16:45.000 tool of communication with your teammates, with your clients, and for external API 168 00:16:45.080 --> 00:16:52.080 consumers. Your docommentation is your product. When you develop a feature and forgot 169 00:16:52.120 --> 00:16:57.639 to document it, you just wasted your time, right, no one ever 170 00:16:57.840 --> 00:17:03.160 find it that closed code, even in open source, like one percent of 171 00:17:03.279 --> 00:17:07.920 users will open your code and read it actually and try to find the feature 172 00:17:08.000 --> 00:17:12.680 that will never mention, like what was never mentioned? That's cruel, but 173 00:17:14.200 --> 00:17:18.960 you know that's true. So with that, I hope I sell the whole 174 00:17:19.359 --> 00:17:27.079 idea of the documentation first approach, Like we write docummentation first and we can 175 00:17:27.200 --> 00:17:33.000 move forward towards you know, technical details next. Yeah, the technical details 176 00:17:33.119 --> 00:17:40.200 is kind of what I wanted to dive into. I mean people have done 177 00:17:40.200 --> 00:17:44.880 TDD. Yeah, you get that thought process ahead of time, you know 178 00:17:45.039 --> 00:17:48.440 you're putting together and yeah, I really like the way that you put it 179 00:17:48.480 --> 00:17:52.240 where yeah, your API is your product because for a lot of consumers it 180 00:17:52.279 --> 00:17:59.079 will be. So let's get into the technical details then, So how do 181 00:17:59.119 --> 00:18:02.720 you do it? Is like reading driven development. You've been mentioned our swag 182 00:18:02.799 --> 00:18:11.279 a bunch two sure, so our swag is call first, not call first, 183 00:18:11.359 --> 00:18:15.839 test first, I guess, but not the documentation first. For me, 184 00:18:15.920 --> 00:18:19.440 at least, you can do that the commutation first, but it's still 185 00:18:19.759 --> 00:18:27.480 much harder to write ARSPEC. Then right, then it's right to write YAMO 186 00:18:27.519 --> 00:18:36.599 files because you can use editors like and everything. And again YAMO is understandable 187 00:18:36.599 --> 00:18:41.559 by other teams as well, so even your like manager can read the YAMO 188 00:18:41.640 --> 00:18:49.319 I guess, especially in the editor like Swagger editor, because they can read 189 00:18:49.400 --> 00:18:56.720 the documentation like the results in the commentation from the start. So hold on, 190 00:18:56.240 --> 00:19:00.160 so you're saying to write so you can write it in an r swag 191 00:19:00.319 --> 00:19:04.039 format and this is just coming from me not having used it, or you 192 00:19:04.039 --> 00:19:10.400 can write it in YAMEL. So yeah, let's sart come back a bit. 193 00:19:10.720 --> 00:19:15.200 So in the documentation first, the whole idea is that you have this 194 00:19:15.759 --> 00:19:25.279 standard, you have this you know, document that describes your API and in 195 00:19:25.359 --> 00:19:32.519 our realm, like with RESTful APIs. That standard is open API. And 196 00:19:32.880 --> 00:19:37.839 by the way, Ruber Rocks has an episode about open API with Josh Bonalat 197 00:19:37.720 --> 00:19:42.200 and I think we will live a link to that episode in show notes. 198 00:19:42.680 --> 00:19:49.440 So Josh also wrote a book about open API, and to me that book 199 00:19:49.480 --> 00:19:56.319 actually looked like four hundred pages of design first. He called that design first 200 00:19:56.519 --> 00:20:00.880 Workshop. So if you want to really dig dive into that topic and see 201 00:20:00.880 --> 00:20:07.839 how it works, like in four hundred pages, you can check his book 202 00:20:07.920 --> 00:20:12.880 out because he does a great job giving a very detailed description of the whole 203 00:20:12.960 --> 00:20:19.240 workflow. But yeah, so we have this standard open API, which is 204 00:20:22.240 --> 00:20:26.880 a strength standard for describing rest foolish APIs. And the resulting document is a 205 00:20:27.039 --> 00:20:36.680 Yama or a Jason file. It contains descriptions for all your requests responses at 206 00:20:36.759 --> 00:20:41.200 leasts like HTTP methods, us quarry, params, headers, body attributes, 207 00:20:41.279 --> 00:20:52.359 whatever all that you need. Right, So that's our center of tension, 208 00:20:52.519 --> 00:20:57.960 that file, and next you can the way you will generate it, the 209 00:20:57.960 --> 00:21:03.400 way you will get it file. That's a different like approaches you can work 210 00:21:03.440 --> 00:21:11.240 on. For example, you can use arswag, which uses metadata from your 211 00:21:11.000 --> 00:21:19.079 request tests and also adds a special DSL to for descriptions and all that stuff. 212 00:21:19.400 --> 00:21:26.440 So as a result, when you're on your tests, it also generates 213 00:21:26.759 --> 00:21:33.279 the file that open API file for you. Or you can obviously just write 214 00:21:33.319 --> 00:21:37.640 it manually and there are plenty of editors and yeah, you can do that 215 00:21:37.720 --> 00:21:44.920 as well. So this is something you can write ahead of time, right, 216 00:21:44.960 --> 00:21:48.599 It's not something that just because because you were saying, you effectively, 217 00:21:48.640 --> 00:21:52.599 you know, write your stuff ahead of time instead of like I said, 218 00:21:52.759 --> 00:21:57.640 I'm kind of imagining something like ar doc where you know, it looks at 219 00:21:57.640 --> 00:22:02.319 your code, reads the comments, but even if it inspected the code. 220 00:22:03.200 --> 00:22:08.200 In this case, you can just write our spec tests or things like that 221 00:22:08.319 --> 00:22:12.440 in order to say this is how the API should perform, and then it 222 00:22:12.480 --> 00:22:17.960 generates the documentation from the DSL. Is that is that what we're looking at 223 00:22:17.960 --> 00:22:25.519 here? Yeah? Ye, but it's your tests and not from your and 224 00:22:25.559 --> 00:22:30.039 not from your code or whatever. So if you haven't implemented yet, fine 225 00:22:30.200 --> 00:22:36.880 true yeah yeah, so yeah. There is also a way to generate open 226 00:22:36.920 --> 00:22:41.240 API from your code. So there are helpers for controllers and all that. 227 00:22:41.359 --> 00:22:45.759 So there are different approaches. The problem with those approaches like when you, 228 00:22:45.799 --> 00:22:52.240 for example, use code like DSL in your controllers. Obviously you need to 229 00:22:52.240 --> 00:22:56.160 write the whole thing. That's a problem. When you you can move that 230 00:22:56.279 --> 00:23:00.440 to tests, now you need to write your tests, which is also sometimes 231 00:23:00.480 --> 00:23:07.759 problematic. You still need to bring all those models and all that. So 232 00:23:08.160 --> 00:23:17.240 even less hard to maintain approach for me at least is writing the whole specification 233 00:23:17.319 --> 00:23:21.799 first at SAMO. Yes, that's that's that might be a problem, but 234 00:23:22.240 --> 00:23:26.799 a like, at the same time, you can read it. JavaScript developer 235 00:23:26.880 --> 00:23:30.559 can read it. Everyone can read it, So I don't I didn't. 236 00:23:30.559 --> 00:23:33.559 I don't know if JavaScript developers speak yamal. I think they speak Jason. 237 00:23:36.839 --> 00:23:45.160 That's also the same format. So right, So so what's your whole process 238 00:23:45.200 --> 00:23:49.319 then? So you sit down, you write out the specification, you poort 239 00:23:49.440 --> 00:23:55.119 that into a test with our swag or do we even do that? So 240 00:23:55.279 --> 00:24:00.359 yeah, if you go my way, which is writing the YAMO first, 241 00:24:02.279 --> 00:24:07.440 then you just open a PR for example, and discuss that documentation with your 242 00:24:07.480 --> 00:24:14.839 team, with your stakeholders whatever, and they all can see what is happening. 243 00:24:15.160 --> 00:24:26.480 You can bring like you can get like really fast answers and gain the 244 00:24:26.480 --> 00:24:32.920 information that you missed while doing that. So that's the first step, and 245 00:24:32.960 --> 00:24:38.920 then you can get the resulting file and start developing your part, and front 246 00:24:40.000 --> 00:24:44.640 end developers can start developing there for part. So it's also like you can 247 00:24:44.680 --> 00:24:52.960 work at the same time, which is a great feature regarding the Uh, 248 00:24:53.160 --> 00:24:59.039 just real quick, while you're developing the spec, are you saying that that 249 00:24:59.160 --> 00:25:03.039 is like made available for people to kind of play with, like in a 250 00:25:03.200 --> 00:25:08.480 UI kind of way. Sure you can generate like if you set up a 251 00:25:08.480 --> 00:25:15.480 PR like CI to watch your PR and to develop like deploy docommodation, why 252 00:25:15.519 --> 00:25:23.039 not. So that depends on your workflow. So yeah, so just yeah, 253 00:25:23.160 --> 00:25:26.160 just to kind of dive into this a little bit, So you generate 254 00:25:26.200 --> 00:25:30.079 the AML, so does it generate the spec for the specs like the RSPEC 255 00:25:30.160 --> 00:25:36.759 specs for you or do you still have to write those separately. So yeah, 256 00:25:37.079 --> 00:25:41.480 in my case, I wrote a JAM that called Schuma, and that 257 00:25:41.680 --> 00:25:49.680 jam adds like three or four helper methods to arsvac or mini tests to your 258 00:25:49.720 --> 00:26:00.519 request tests. So to test your request against the specification, all all you 259 00:26:00.599 --> 00:26:07.079 need is to prepare the request, call it, and then write something like 260 00:26:10.839 --> 00:26:19.480 assert the specification or it depends on the framework, but like it is expected 261 00:26:19.519 --> 00:26:26.359 to conform schema the code of response that you are looking for. That's it, 262 00:26:26.680 --> 00:26:30.400 like one line. With that one line, you are like, you 263 00:26:30.519 --> 00:26:37.839 will test all the headers that you write in your documentation, in your specification, 264 00:26:37.400 --> 00:26:42.519 all the attributes, body attributes like request response, all that with just 265 00:26:42.559 --> 00:26:47.799 one line. So that's that's a great way to clean up your tests. 266 00:26:47.839 --> 00:26:52.039 I guess, yeah, that sounds awesome. So then so then you just 267 00:26:52.039 --> 00:26:56.400 go and implement, right, So then you're writing your your API through your 268 00:26:56.440 --> 00:27:03.400 controllers or I saw in your article you're using great API, which I may 269 00:27:03.440 --> 00:27:07.119 ask you about in a minute, but yeah, as a way, yeah, 270 00:27:07.960 --> 00:27:15.359 yeah, I love great API and I hate great API. So anyway, 271 00:27:15.680 --> 00:27:21.119 it's yeah. So so that that's pretty much it. So you're you're 272 00:27:21.640 --> 00:27:26.720 you've got your documentation then in Yamel, and you've got your tests that run 273 00:27:26.759 --> 00:27:30.039 and things like that. So I guess the other thing that I'm wondering about 274 00:27:30.119 --> 00:27:34.440 here, because there are some benefits to open API, right, yeah, 275 00:27:34.680 --> 00:27:38.799 I'm pretty sure you can. You know, if you have open API compliant 276 00:27:38.839 --> 00:27:45.400 documentation, then you can import it into Postman and things like that. And 277 00:27:45.519 --> 00:27:48.279 if you haven't tried to Postman, you should. It's it's a terrific tool. 278 00:27:48.640 --> 00:27:55.440 But I guess my question is what about written documentation Because to a certain 279 00:27:55.480 --> 00:27:57.960 degree, yeah, just having it pull up and say, you know, 280 00:27:59.599 --> 00:28:00.759 yeah, you're going to send this kind of a request, You're going to 281 00:28:00.759 --> 00:28:03.480 get this kind of a response, You're going to see this kind of behavior 282 00:28:03.759 --> 00:28:07.519 you know on the other end. But sometimes you need a little bit more 283 00:28:07.559 --> 00:28:11.880 than that. So how how far does this get you? As far as, 284 00:28:11.960 --> 00:28:14.759 like you said, the API being the product, how far does this 285 00:28:14.880 --> 00:28:17.599 get you as far as somebody like me coming along and going okay, how 286 00:28:17.640 --> 00:28:21.279 do I talk to this app and being able to get the information I need 287 00:28:21.319 --> 00:28:26.599 out of it without necessarily being able to read the YAMO file or being able 288 00:28:26.599 --> 00:28:33.599 to see it. Sure, So open API allows you to extend itself, 289 00:28:33.720 --> 00:28:41.440 like with special X keywords. So all of those generators, like the commendation 290 00:28:41.759 --> 00:28:48.240 generators, they come with those special key words that you kind of use to 291 00:28:48.519 --> 00:28:56.960 generate like a special pages and use and mark down to explain everything you want. 292 00:28:56.559 --> 00:29:04.200 So there's also the idea that you can tag use tags to your requests 293 00:29:04.240 --> 00:29:08.240 and also add a description to your tag. So for example, you come 294 00:29:08.279 --> 00:29:15.880 to users tag, it's like a big chunk of your documentation and you can 295 00:29:15.960 --> 00:29:22.000 put marda on there and just kind of explain everything about users you want. 296 00:29:22.440 --> 00:29:30.079 So, yeah, that's all available there. So I'm curious what your approaches 297 00:29:30.200 --> 00:29:34.839 for like, you know, sample data. You know how that's definitely one 298 00:29:34.880 --> 00:29:41.079 of the like hardest problems I find with even document documenting specs, right, 299 00:29:41.119 --> 00:29:44.680 Like it's how do you fake the data in a way that is also like 300 00:29:45.279 --> 00:29:48.759 accurate to the usage, right, Like you can't just like sample production data 301 00:29:48.799 --> 00:29:52.119 all the time, and so like what is your approach for that? And 302 00:29:52.160 --> 00:29:56.200 then maybe how does like the opening having it as a separate specification, how 303 00:29:56.200 --> 00:30:03.720 do how does that help you know in that process? Right? So to 304 00:30:03.799 --> 00:30:10.759 me personally, I was interested in that at some point, but then it 305 00:30:10.920 --> 00:30:18.880 wasn't needed on other like projects, So I'm not currently you know, up 306 00:30:18.880 --> 00:30:22.559 to date here, But there are different ways. For example, there is 307 00:30:22.599 --> 00:30:33.480 an issue in SCUMA two allow such like interface for adding examples from the test 308 00:30:33.559 --> 00:30:41.519 data, like providing that and adding that to the specification. I hopefully will 309 00:30:44.039 --> 00:30:53.160 come to that issue someday. So another thing is that, like what's the 310 00:30:53.200 --> 00:30:56.759 issue that you want to fix if you want to fix the problem that your 311 00:30:57.759 --> 00:31:04.640 example data might be out of think with the rules that you described, there 312 00:31:04.680 --> 00:31:12.319 are like plenty of tools to date that because open API it's a common standard, 313 00:31:12.759 --> 00:31:18.680 there are like different languages and different tools. You are not scoped to 314 00:31:18.880 --> 00:31:26.079 Rugby only tools, so there is like a lot of tools for almost every 315 00:31:26.799 --> 00:31:34.160 idea and thing to do. So yeah, I don't remember the name for 316 00:31:34.480 --> 00:31:40.000 that tool, but it's definitely there. Yeah, I mean, just as 317 00:31:40.000 --> 00:31:42.160 an example, I think of your you know, original use case where you 318 00:31:42.200 --> 00:31:45.279 had the end date that was like to infinity. You know, like, 319 00:31:45.559 --> 00:31:48.240 how do you, like, how do you even model that from a fake 320 00:31:48.319 --> 00:31:53.680 data perspective? You know, how did you in this case like document or 321 00:31:55.480 --> 00:32:00.640 maybe not even document, but specify that in the specification. The specification allows 322 00:32:00.680 --> 00:32:06.839 you to use. It depends on the version, Like if it's version three 323 00:32:06.880 --> 00:32:12.200 point oh, you can say that it's noble true. And if it's like 324 00:32:12.400 --> 00:32:20.119 more common like the current version three point one, you can use array of 325 00:32:20.200 --> 00:32:23.880 types. I guess that's something that you can do. And yeah, that's 326 00:32:24.279 --> 00:32:31.920 by the way, that's painful because if you will write now without like not 327 00:32:32.079 --> 00:32:37.319 as a string, that will be now the data not the string, which 328 00:32:37.359 --> 00:32:43.079 is painful. But anyway, so yeah, and in that case, I 329 00:32:43.160 --> 00:32:49.960 don't think you can do anything, but just using your plane like English, 330 00:32:50.240 --> 00:32:57.200 to just describe what is happening, because that's what the commutation does. Probably 331 00:32:57.240 --> 00:33:00.680 you can read the commentation that contains only examples, right, that's a strange 332 00:33:00.680 --> 00:33:06.200 recommentation like rails guides and there is just a list of you know, you 333 00:33:06.240 --> 00:33:10.359 know there is a site with like something in fifteen minutes or something like that, 334 00:33:10.480 --> 00:33:15.279 like different languages and all that. That's just one big chunk of example. 335 00:33:16.440 --> 00:33:25.920 Yeah, that's that's you can use that. But so when you're designing 336 00:33:27.000 --> 00:33:30.599 APIs right, So let's say you you're like, all right, you know, 337 00:33:30.680 --> 00:33:35.240 I need an API for my application, and I'm putting it together, 338 00:33:35.559 --> 00:33:40.519 and you put it out for feedback from your coworkers or you know, maybe 339 00:33:40.559 --> 00:33:46.440 customers or whoever. Right, what kind of feedback are you generally looking for? 340 00:33:46.599 --> 00:33:51.200 And how do you prompt them to give that to you? Because I 341 00:33:51.240 --> 00:33:52.960 swear like half the time when I ask for any kind of feedback, like 342 00:33:52.960 --> 00:33:58.799 in a PR or something, it's just like, yep, that's good, 343 00:33:59.119 --> 00:34:01.880 right, So and I want real feedback, right, It's like, no, 344 00:34:02.599 --> 00:34:07.200 we don't do it that way, or this would make this easier on 345 00:34:07.279 --> 00:34:13.480 me when I'm building some other thing, right, Yeah, so I don't 346 00:34:13.519 --> 00:34:19.519 know like that feedback. It sounds like the feedback from people who are not 347 00:34:19.679 --> 00:34:24.360 interested in the result, you know. And I don't mean like in the 348 00:34:24.440 --> 00:34:28.519 rude way. I mean like, yeah, that will be fine. I 349 00:34:28.920 --> 00:34:32.039 don't really care because you will make it work, right, I do understand 350 00:34:32.039 --> 00:34:37.239 that you will do that. But in API, that's an interface that will 351 00:34:37.280 --> 00:34:43.400 be used by those people, so they kind of they want it to be 352 00:34:43.800 --> 00:34:47.199 easy for them. So maybe they already have thought about some edge cases in 353 00:34:47.239 --> 00:34:51.960 the UI or something like that. Again, the pagenation is a great example 354 00:34:52.000 --> 00:34:55.400 because for example, they want to use like infinite scrolling and they can use 355 00:34:57.079 --> 00:35:01.199 like cursor pagenation, or they want to use pages and you did the crystal 356 00:35:01.199 --> 00:35:07.159 opagenation and it's obviously not that something that they can use. So yeah, 357 00:35:07.239 --> 00:35:13.159 okay, yeah, well I'm kid. This makes me think. So I'm 358 00:35:13.199 --> 00:35:16.360 in graphicoll a lot. That's what all of our clients use, and it 359 00:35:16.400 --> 00:35:22.519 makes you think, like, of I love it, but it makes it 360 00:35:22.559 --> 00:35:27.119 does make me think, Like, you know, a lot of times you'll 361 00:35:27.119 --> 00:35:31.559 have the front end people separate from the back end and you'll have the same 362 00:35:31.599 --> 00:35:35.840 stories kind of working in parallel, right, like where somebody will be working 363 00:35:35.920 --> 00:35:38.960 the interface and somebody will be working in the back end stories, and you'll 364 00:35:39.039 --> 00:35:44.280 race kind of like you know, to make sure that the you know, 365 00:35:44.360 --> 00:35:47.119 front end team can align with the back end, but also like that you're 366 00:35:47.159 --> 00:35:51.559 supporting everything that they need. And a lot of times people will just like 367 00:35:51.639 --> 00:35:55.920 make you know, fake wrappers of what they might expect to need, you 368 00:35:55.960 --> 00:36:00.679 know, in order to build whatever they're building. You know, what what 369 00:36:00.840 --> 00:36:06.800 is your like where does that uh you know, specification aspect fit in that 370 00:36:06.920 --> 00:36:10.199 kind of workflow where you know people need to use it right away and the 371 00:36:10.360 --> 00:36:19.679 specification gets molded kind of as it's getting worked on. Yeah. So the 372 00:36:19.719 --> 00:36:24.280 great thing about open a BA is that you have mock servers for example, 373 00:36:24.400 --> 00:36:31.760 so they can use them and you don't need to touch a keyboard for that, 374 00:36:31.880 --> 00:36:38.239 so they will have their more data and you don't need to like do 375 00:36:38.360 --> 00:36:46.079 that yourself in the back end code. Another thing is that it's fine to 376 00:36:47.679 --> 00:36:53.280 get back to the specification. Uh, it will happen like all humans, 377 00:36:53.360 --> 00:36:59.840 as I said, so, yeah, but the probability I think is my 378 00:37:00.920 --> 00:37:08.760 you know less, it's much less common to go back and fix something if 379 00:37:08.800 --> 00:37:20.280 you already thought about that in the first place. So Valentino brought up graph 380 00:37:20.360 --> 00:37:22.960 ql, and I have not talked to anybody about open api for a long 381 00:37:22.960 --> 00:37:25.559 time, and I haven't really looked at swagger open api for a while. 382 00:37:28.119 --> 00:37:34.039 Does this work on systems like graph ql or is it only like rest systems? 383 00:37:35.440 --> 00:37:40.119 So right now it's only rest systems, and it's it's even hard to 384 00:37:40.400 --> 00:37:49.159 implement, like describe something like RPC because that's just one end point and just 385 00:37:49.480 --> 00:37:55.199 what open api looks like that doesn't work with such cases. There is a 386 00:37:55.320 --> 00:38:01.280 new version, like the version four point zero Moon Bulk. I guess it's 387 00:38:01.360 --> 00:38:09.079 it's it's called so in that version they do might like they try to support 388 00:38:10.199 --> 00:38:16.159 such cases when you have one end point and a lot of different like actions. 389 00:38:17.360 --> 00:38:24.079 So I don't think that graph kill is like interesting for them because it 390 00:38:24.199 --> 00:38:30.119 already has the scheme and all that. But yeah, those cases with when 391 00:38:30.199 --> 00:38:37.440 you use just one end point and a lot of stuff happening in there because 392 00:38:37.440 --> 00:38:40.320 of like I do you know, like different headers or very prims. That's 393 00:38:40.559 --> 00:38:47.519 what they try to fix in the new version. So one other thing that 394 00:38:47.559 --> 00:38:52.559 I think would be good to cover for folks is we've used the terms open 395 00:38:52.599 --> 00:38:59.159 api and Swagger interchangeably. You want explain what they are. I don't know 396 00:39:00.079 --> 00:39:06.719 about you, but I didn't because that's different things. Actually, okay, 397 00:39:07.400 --> 00:39:15.800 I may have used the Yeah. So Swagger is a company that developed the 398 00:39:15.800 --> 00:39:20.400 first draft, like the first I guess, a couple versions of open api 399 00:39:20.760 --> 00:39:27.920 the thing and called that Swagger at the time, and they decided to like 400 00:39:28.199 --> 00:39:34.559 they were cured by another company, I guess I don't like something beat. 401 00:39:35.039 --> 00:39:38.880 Sorry I don't remember the name, but anyway doesn't matter. So they just 402 00:39:39.639 --> 00:39:45.440 decided to make it open source, the whole specification, and then they renamed 403 00:39:45.440 --> 00:39:52.000 it to open api and made it public. I mean, like open source 404 00:39:52.280 --> 00:40:00.960 and Swagger that name they decided to keep and name their tools with that name. 405 00:40:00.079 --> 00:40:05.800 So when you talk about Swagger right now, you probably refer to their 406 00:40:06.039 --> 00:40:15.119 tool in like Swagger UI, Swager Editor, and so on. Okay, 407 00:40:15.199 --> 00:40:20.800 so all of this, uh, you know a p I automation and schema 408 00:40:20.880 --> 00:40:28.360 documentation just makes me think of function calling uh in the AI realm uh are 409 00:40:28.440 --> 00:40:35.039 you are you using this uh kind of methodology to like for code generation purposes 410 00:40:35.199 --> 00:40:40.079 or for like augmenting you know, AI workflows and stuff like that. So 411 00:40:40.920 --> 00:40:46.320 uh, as I said, I prefer to write open API dogs manually. 412 00:40:46.559 --> 00:40:52.360 So yeah, in that case, something like uh copilot, it helps a 413 00:40:52.360 --> 00:41:01.840 lot to write them. Uh so. But regarding code generation, actually there 414 00:41:01.880 --> 00:41:07.400 are generators in the open API realm. It's not about AI. But anyway, 415 00:41:07.679 --> 00:41:13.079 since we are talking about that, you can generate client side as the 416 00:41:13.159 --> 00:41:17.320 case, which will include validation, cerilization, all the good stuff. You 417 00:41:17.360 --> 00:41:22.599 don't need to write that. And like, there are different languages and versions. 418 00:41:22.960 --> 00:41:30.079 There is even version for Ruby, and they even have SDK generators for 419 00:41:30.239 --> 00:41:36.599 server code, so you can generate your server I don't know of any Ruby 420 00:41:36.639 --> 00:41:40.280 gems for that, like Ruby generators for that. But still if you want 421 00:41:40.320 --> 00:41:46.119 to generate gaoscript something, yeah, you can do that. So yeah, 422 00:41:46.239 --> 00:41:51.719 I don't know if I answered your question. I was just looking at your 423 00:41:52.159 --> 00:41:57.960 Schuma Jason stuff where it validates the schema and that's very much kind of like 424 00:41:58.000 --> 00:42:02.599 what function calling does when you're working with something like open AI, right, 425 00:42:04.440 --> 00:42:06.920 So I'm just curious if, like you were, you were using it maybe 426 00:42:06.960 --> 00:42:10.400 for that purpose in the Ruby side. Now no, I may, I 427 00:42:10.440 --> 00:42:20.360 may try it out. So Jason Scoma is another gem that like implements another 428 00:42:20.519 --> 00:42:25.320 standard that is used under the open API, So when you describe different arm 429 00:42:27.280 --> 00:42:30.480 things in open API, it might be like quay, parameters, body, 430 00:42:30.559 --> 00:42:38.000 whatever you use. Actually use Jason Schema. In version three point zero, 431 00:42:38.119 --> 00:42:44.280 it was like subset superset of Jason Schema, which was painful for everyone. 432 00:42:44.599 --> 00:42:49.280 So with version three point one, which is the current question of open a 433 00:42:49.320 --> 00:42:54.679 PA, they first of all they upgraded the version like for five major releases 434 00:42:54.719 --> 00:43:00.800 of Jason Schema, which is that's a different story. But yeah, they 435 00:43:01.320 --> 00:43:08.119 also made it like the standards so you can use that and yeah, that's 436 00:43:08.159 --> 00:43:14.760 that's a great tool actually for foundation. Yeah, it's funny. You can 437 00:43:15.199 --> 00:43:19.360 you can pass schemas uh to you know, these large language models, and 438 00:43:19.719 --> 00:43:22.440 it knows how to adhere to it even without like the function calling aspect, 439 00:43:22.440 --> 00:43:30.519 which is kind of interesting. Yeah, So I'm curious like now that you 440 00:43:30.679 --> 00:43:35.320 have like this documentation first like approach, like how do people like it on 441 00:43:35.360 --> 00:43:37.519 your team? Like is it is it like everybody's excited about it or is 442 00:43:37.559 --> 00:43:43.000 it like kind of a struggle to get people on our people still hesitant? 443 00:43:43.159 --> 00:43:46.199 Like how is it working out? In depends? It depends. So for 444 00:43:46.239 --> 00:43:52.320 example, what Polkan he heads it, I guess, I know, like 445 00:43:52.800 --> 00:43:58.920 writing something manually without DSL. He just but you know, the approach. 446 00:43:59.159 --> 00:44:06.239 It's good for small teams if there are different stacks, but if you work 447 00:44:06.280 --> 00:44:10.599 in a full stack team or something like that, that's overkill. Basically, 448 00:44:10.679 --> 00:44:16.840 if you don't need to discuss those APIs or for example, uh Inertia Jazz, 449 00:44:17.519 --> 00:44:24.119 you can use that to just eliminate the whole AP I think from from 450 00:44:24.119 --> 00:44:31.800 your application because I don't know if you know about in Airsha, but it's 451 00:44:31.199 --> 00:44:39.360 a geoscreet library. Plus it has plug ins for for example, rails and 452 00:44:39.559 --> 00:44:49.760 for different front end frameworks like React view as well. Yeah, so when 453 00:44:49.800 --> 00:44:57.199 you use that in your application, you just replace your view files with whatever 454 00:44:57.360 --> 00:45:02.639 framework you decided to work one, so for example with React, and there 455 00:45:02.679 --> 00:45:08.159 is no API for that, so it's just like passing the whole bucket of 456 00:45:08.920 --> 00:45:15.159 data just renders that. So yeah, you can remove the whole API thing 457 00:45:15.239 --> 00:45:21.880 from your application and yeah, no need for manual yamal writing. Yeah. 458 00:45:21.920 --> 00:45:27.159 I think it even works kind of like in an SPA style of app too, 459 00:45:27.280 --> 00:45:30.760 which is interesting. So is there anything else that we should know about 460 00:45:30.760 --> 00:45:37.400 with open API and Swagger and all that stuff. Yeah, I know, 461 00:45:37.639 --> 00:45:45.320 like if you use open API to document things, whatever you use like ARSWAG 462 00:45:45.599 --> 00:45:53.480 or SCUMA or whatever, please dig deep into the tooling stuff that they have, 463 00:45:53.960 --> 00:45:59.559 because it doesn't matter if you generate your documentation with ARSPAC for example, 464 00:46:00.519 --> 00:46:07.159 you still can use all those tools to for example, link your API documentation 465 00:46:07.559 --> 00:46:13.320 and with open API your API it becomes I know, you can touch it, 466 00:46:13.440 --> 00:46:20.000 right, it's a whole new experience because that's that's something real. And 467 00:46:20.679 --> 00:46:24.559 since it's real, you can lint it. You can use static analyzers on 468 00:46:24.639 --> 00:46:31.159 that, and you can, for example, you can use tools to catch 469 00:46:34.159 --> 00:46:43.239 like some errors or for example all WSP problems with security all that. So, 470 00:46:43.960 --> 00:46:49.800 yeah, that's really powerful idea and please please play with that. You 471 00:46:49.840 --> 00:46:55.519 can use linters. You can force everyone to add descriptions to artifact using those 472 00:46:55.599 --> 00:47:01.320 tools because you can use linter and add that to CI and yeah, that 473 00:47:01.400 --> 00:47:07.639 will blow up unless someone did their work properly. Nice. It sounds like 474 00:47:07.679 --> 00:47:13.960 what you're saying, there's there's no excuse for for API documentation. Yeah yeah, 475 00:47:15.360 --> 00:47:21.199 oh but I like my excuses. They make me comfortable being lazy. 476 00:47:21.679 --> 00:47:27.880 Do you do you create API documentation for like side projects and just one off 477 00:47:28.039 --> 00:47:32.679 things that you're trying out. Ah, that's such a painful question actually because 478 00:47:36.000 --> 00:47:42.239 all my side projects they have more like gems and a logical thing to do, 479 00:47:42.400 --> 00:47:46.440 Like why not document your gems first? Right? Like right, no, 480 00:47:47.119 --> 00:47:52.599 No, my gems has next to zero documentation. That's so painful. 481 00:47:52.719 --> 00:47:58.920 You asked that. That's so rude, Like we're almost almost done with the 482 00:47:59.000 --> 00:48:02.519 podcast and you yeah, we never would have known, to be honest, 483 00:48:02.599 --> 00:48:07.960 Like I'm curious about this question, right because like, uh, you know, 484 00:48:08.320 --> 00:48:14.719 why don't you Why don't we like have this creativity and like experimentation like 485 00:48:14.840 --> 00:48:19.960 with a documentation first thing, like what is like the barrier from us like 486 00:48:20.079 --> 00:48:24.679 thinking about our ideas in a specification way versus like where we're trying you know, 487 00:48:24.880 --> 00:48:29.199 Like, I don't know. It's a it's a question I think about 488 00:48:29.199 --> 00:48:36.000 a lot. That's all about like the talk that I told about from aeral 489 00:48:36.079 --> 00:48:40.000 kaplan. It's all about that that you are. You can write that documentation 490 00:48:40.239 --> 00:48:45.719 upfront because you have to, Like you are so energetic at that moment you 491 00:48:45.760 --> 00:48:51.320 are like creating stuff and it's it's easy. You you want to like understand 492 00:48:51.320 --> 00:48:55.679 it yourself, and you think I will, I will do that way or 493 00:48:55.760 --> 00:49:01.159 that way, and I need to fix those edch case and you know at 494 00:49:01.159 --> 00:49:07.639 that moment, that's just when you can do that after like after you did 495 00:49:07.679 --> 00:49:15.000 the all work. It's just like describing all that and it's the worst part. 496 00:49:15.599 --> 00:49:22.519 Well, it's funny because not just documentation, but in other areas, 497 00:49:22.599 --> 00:49:25.199 right, I mean, I still see people that and I've gotten out of 498 00:49:25.199 --> 00:49:30.480 the habit of writing tests right, or writing good tests, or you know 499 00:49:30.599 --> 00:49:35.360 some of the other code hygiene things that I do on the front end that 500 00:49:35.400 --> 00:49:40.000 I know I should do right. And so it really just comes down to, 501 00:49:40.760 --> 00:49:45.000 I mean, not even whether or not you believe it or believe it 502 00:49:45.000 --> 00:49:47.960 to be a good thing or worth your time. It's a matter of discipline. 503 00:49:47.960 --> 00:49:52.039 And it seems like a lot of this stuff just comes down to discipline. 504 00:49:52.119 --> 00:49:57.440 Right. Are you committed to writing the best coach you can? Are 505 00:49:57.559 --> 00:50:02.559 you committed to delivering highest quality product you can? Right? I mean, 506 00:50:02.800 --> 00:50:07.280 obviously as you approach perfect it takes more and more effort to get it, 507 00:50:08.079 --> 00:50:10.719 you know, to get more quality out of it. But you know, 508 00:50:10.800 --> 00:50:16.880 are you committed to putting out stuff that just you know, ticks all the 509 00:50:16.920 --> 00:50:22.079 boxes on stuff that is maintainable? Right? Because we're not talking about. 510 00:50:22.280 --> 00:50:23.639 Oh, you know, I'm going to write this documentation so that I can 511 00:50:23.679 --> 00:50:28.719 pat myself on the back. I'm writing this documentation because I know that it'll 512 00:50:28.760 --> 00:50:31.480 make somebody else's life easier, right, I know that it'll make it easier 513 00:50:31.480 --> 00:50:36.000 to maintain. I know that it'll do these things for me. And so 514 00:50:36.559 --> 00:50:39.760 it really is down to discipline and whether or not you're willing to do the 515 00:50:39.840 --> 00:50:45.360 sometimes tricky stuff in order to make it work. But the thing that I 516 00:50:45.440 --> 00:50:50.000 found, too is that the more I do those kinds of things, the 517 00:50:50.039 --> 00:50:54.039 better off I am because my skill level goes up. Right, I can 518 00:50:54.119 --> 00:51:00.639 more easily tackle more difficult problems because I've done the discipline then to write to 519 00:51:00.679 --> 00:51:04.280 make sure that my documentation is up to date, or to make sure that 520 00:51:04.320 --> 00:51:09.119 my tests run and pass and that I have decent test coverage, or you 521 00:51:09.159 --> 00:51:16.639 know that I am breaking up my huge models or giant controllers or whatever other 522 00:51:16.719 --> 00:51:23.000 thing right that I know I should do. I'm doing it because it makes 523 00:51:23.039 --> 00:51:28.000 a difference later later on down the road. So anyway, I'll get off 524 00:51:28.000 --> 00:51:31.159 my soapbox. But the discipline questions, one thing that I like to hit 525 00:51:31.320 --> 00:51:37.079 is, you know what you're supposed to do. You doing it the processes. 526 00:51:37.519 --> 00:51:42.760 The processes can help you also, like links, Yeah, just just 527 00:51:42.840 --> 00:51:50.280 turned on the lint that like what it was like the linter that tells you 528 00:51:50.320 --> 00:51:59.159 to write five lines of code that months for a Oh right, well I 529 00:51:59.159 --> 00:52:01.960 don't always agree with But the thing is is that you can, like with 530 00:52:02.039 --> 00:52:06.119 rubocop, you can make it whatever you want it to be. Right, 531 00:52:06.239 --> 00:52:09.400 So you can tell it no, I'm okay with ten line methods, right, 532 00:52:09.519 --> 00:52:14.000 or you can just turn the rule off if that's something, or maybe 533 00:52:14.000 --> 00:52:16.079 it just check it, check for egregious stuff. If it's fifty lines, 534 00:52:16.119 --> 00:52:22.280 then I have a problem, right, I don't know, but yeah, 535 00:52:22.360 --> 00:52:24.440 getting into it, it's like okay. And that's the other thing is is 536 00:52:24.519 --> 00:52:28.679 I think people get into the mindset of my documentation has to be perfect the 537 00:52:28.679 --> 00:52:32.679 first time or right, or you know, the linking rules. The linking 538 00:52:32.800 --> 00:52:36.880 rules have to be exactly what I want. Sometimes you have to fuss with 539 00:52:36.920 --> 00:52:38.559 it a little bit in order to figure out and it's not even to get 540 00:52:38.599 --> 00:52:42.079 what you want, it's to figure out what you want so that you can 541 00:52:42.119 --> 00:52:45.880 have it right. And so it's you know, five lines of code and 542 00:52:45.920 --> 00:52:50.800 a method is way too restrictive, right. I just I find myself frequently 543 00:52:50.840 --> 00:52:55.800 needing eight right, so I'm gonna bump it to ten right. Totally fine, 544 00:52:57.079 --> 00:53:01.960 go to ten right, not hurting anybody. But you know a lot 545 00:53:02.000 --> 00:53:06.119 of times those are the other excuses that we used to not do the stuff 546 00:53:06.119 --> 00:53:08.880 that we know we are to have in place. The cool stuff about like 547 00:53:09.159 --> 00:53:13.679 all those splinter rules that you can, yeah, turn on all them, 548 00:53:13.920 --> 00:53:17.760 but that's an opt in action. You need to think about that. Why 549 00:53:19.280 --> 00:53:22.800 can I do that? It's like strong migrations jam that allows you to ignore 550 00:53:22.880 --> 00:53:30.039 all those rules, like you're trying to like break and you know, add 551 00:53:30.039 --> 00:53:35.440 a new index for example, to the table, and it yells at you 552 00:53:35.519 --> 00:53:38.519 like, hey guy, that that will be like painful, there is too 553 00:53:38.559 --> 00:53:44.760 much data. But you know that it's like ten lines of like ten rows, 554 00:53:44.880 --> 00:53:47.679 so you can do that. So it's all about that, you know, 555 00:53:47.840 --> 00:53:57.840 thinking yep, I don't want to think no. I think I'm curious, 556 00:53:57.880 --> 00:54:00.880 like how how all of this will pan out in the long run. 557 00:54:01.400 --> 00:54:06.079 And it makes me think of like, you know, things like you know 558 00:54:06.159 --> 00:54:09.119 co pilot or something like that, where you know you're just documenting things and 559 00:54:09.159 --> 00:54:15.639 then it just fills stuff out and it'll it'll be interesting to see how those 560 00:54:15.760 --> 00:54:22.440 kinds of developers evolve over time and and hopefully like you know, the auto 561 00:54:22.480 --> 00:54:29.400 documentation test aspects of it just like happen. But but I don't think we're 562 00:54:29.440 --> 00:54:35.920 there anywhere near term. But I do think about like you know, Gary 563 00:54:35.920 --> 00:54:40.280 Bernhardt's like original destroyeral software stuff, and when I was getting into test, 564 00:54:40.400 --> 00:54:44.880 you know, for the first time and just seeing that like workflow, like 565 00:54:44.920 --> 00:54:46.639 he's just wild, like, oh yeah, let me open up a test 566 00:54:46.679 --> 00:54:50.480 so I can make sure that this thing works right. And like before he 567 00:54:50.519 --> 00:54:53.119 does anything like no codes written right, like and it's like, okay, 568 00:54:53.239 --> 00:54:58.199 I want it. I describe basically it's documentation, right, I describe how 569 00:54:58.239 --> 00:55:00.599 I want this thing to work, and then I go make sure that it 570 00:55:00.679 --> 00:55:05.639 works right. And that's definitely a very like it's a shift in how like 571 00:55:05.719 --> 00:55:07.840 you're kind of taught like coding wise, where it's like all right, just 572 00:55:07.880 --> 00:55:12.559 go try to do something right. And I think that's maybe why we have 573 00:55:12.599 --> 00:55:15.880 a hard time in our side projects like documenting things, is like we just 574 00:55:15.920 --> 00:55:19.360 want to go try it right, and we just want to like mess around 575 00:55:19.360 --> 00:55:23.039 with stuff, and maybe we need to like veer away from that like thinking 576 00:55:23.360 --> 00:55:30.800 and learn how to mess around with things in a more controlled way. Yeah, 577 00:55:30.840 --> 00:55:37.480 there was another wild idea, like I think it's from then when when 578 00:55:37.519 --> 00:55:44.239 he was in soft boats. So it was idea that he will just remove 579 00:55:44.760 --> 00:55:50.880 all non committed code like once for a while when so when he work on 580 00:55:50.920 --> 00:55:54.719 something, he gains more information, he knews what he wants to do, 581 00:55:55.000 --> 00:56:00.199 and if it's not committed then it's okay. He will just write it again 582 00:56:00.280 --> 00:56:02.519 and it will be better. Something like that. So yeah, not another 583 00:56:04.159 --> 00:56:12.480 extreme idea. Yeah, was it Toby Luke from Shopify. He's notorious for 584 00:56:12.760 --> 00:56:16.480 doing that, for just like nuking his entire you know, stuff that hasn't 585 00:56:16.480 --> 00:56:21.159 made it and just rewriting it again. And I forget what. Yeah, 586 00:56:21.199 --> 00:56:25.960 there was a there was a stuff like that. Yeah, I forget what 587 00:56:27.000 --> 00:56:34.360 they called that. I think it was red green. And then there was 588 00:56:34.400 --> 00:56:37.599 something else and it was basically you throw the code away and do it code 589 00:56:37.639 --> 00:56:40.199 away. And I can't remember what he called it, but yeah, I 590 00:56:40.199 --> 00:56:44.440 mean, I don't know how many times I've like gone and done code and 591 00:56:44.480 --> 00:56:47.519 then had just like it disappeared because I committed the wrong thing or like missed 592 00:56:47.639 --> 00:56:52.159 something or rebase right and they're like, whoops, I don't know where that 593 00:56:52.199 --> 00:56:55.199 went. And then I just like rewrote it and it was good. So 594 00:56:57.239 --> 00:57:00.639 it can be good, but it's frustrated. All right, Well, let's 595 00:57:00.639 --> 00:57:06.119 go ahead and get into the picks. Oh it's it's uh, it's TCRs, 596 00:57:06.159 --> 00:57:09.079 test and commit and then revert or test and then commit to revert and 597 00:57:09.079 --> 00:57:12.360 so if it's not good enough to commit, then you revert and do it 598 00:57:12.400 --> 00:57:17.480 again. Anyway, let's do picks. Let's let's uh start wrapping up Valentino. 599 00:57:17.519 --> 00:57:21.599 What are your picks? So, as my recurring trend seems to be, 600 00:57:21.760 --> 00:57:24.679 I have a lot of AI picks here. One is called udio dot 601 00:57:24.719 --> 00:57:32.840 io udio dot com. Sorry. Uh. It's basically a really awesome uh 602 00:57:34.360 --> 00:57:38.320 ai music generator where you just give it a prompt and it generates like incredible 603 00:57:38.360 --> 00:57:43.960 songs. This is wild. But it also lets you like focus on either 604 00:57:44.239 --> 00:57:47.880 just like the instrumental aspect or you can break it out and I've been messing 605 00:57:47.880 --> 00:57:57.159 around with it's so much fun. My other pick is uh I came across 606 00:57:57.519 --> 00:58:00.800 I've been playing with Allama a lot lately, which is if you're not familiar, 607 00:58:00.840 --> 00:58:04.480 just lets you try out a bunch of different large language models that are 608 00:58:04.599 --> 00:58:09.800 open source and available, and I came across this project called lit GPT, 609 00:58:10.480 --> 00:58:17.199 which basically is OLAMA but with the ability to pre train and fine tune, 610 00:58:17.519 --> 00:58:23.119 and it adds a bunch of those aspects of large lange model development on top 611 00:58:23.199 --> 00:58:27.000 of it. And so I've been messing around with This is a lot of 612 00:58:27.000 --> 00:58:30.800 fun and it makes it super easy to get started with all that stuff. 613 00:58:31.079 --> 00:58:37.960 So I'd recommend checking that out. Very cool. I'm trying to pull together 614 00:58:37.039 --> 00:58:43.599 some stuff. Maybe I shouldn't announce it before I have it ready. I'm 615 00:58:43.639 --> 00:58:49.440 trying to pull together some stuff to put together an AI and Ruby summit and 616 00:58:49.639 --> 00:58:52.559 just bringing people who are working on all this stuff because it seems like there's 617 00:58:52.599 --> 00:58:58.280 a lot and it's very very interesting. So anyway, I don't have dates 618 00:58:58.360 --> 00:59:02.320 or anything or even know who this speakers are, but yeah, looking at 619 00:59:02.360 --> 00:59:07.559 that. My picks, I usually start out with a board game, and 620 00:59:07.360 --> 00:59:12.199 I'm just I'm not thinking of a board game I really want to pick, 621 00:59:12.320 --> 00:59:16.440 so I'm going to pass on that. I am going to pick. If 622 00:59:16.719 --> 00:59:22.679 you haven't read it yet, folks, I Usuh, who's one of our 623 00:59:22.719 --> 00:59:29.239 other co hosts, he wrote the Rails and hot Wire Codex, and I 624 00:59:29.320 --> 00:59:32.480 decided, you know, because sometimes I how do I put it? I 625 00:59:32.480 --> 00:59:37.760 guess in the past the way that I've learned things is just by kind of 626 00:59:37.119 --> 00:59:39.559 I need this, I need it to do it, and so I'm going 627 00:59:39.599 --> 00:59:44.920 to go find the way that it gets done. And he kind of walks 628 00:59:44.920 --> 00:59:49.199 you through the process of doing the things that you're you know that you're looking 629 00:59:49.239 --> 00:59:52.239 at there. And so I'm about a quarter of the way through the book 630 00:59:52.400 --> 00:59:57.360 at this point, and so far, he's walked you through building your own 631 00:59:57.440 --> 01:00:06.519 authentication, He's walked you through through setting up Turbonative for Android and iOS. 632 01:00:07.239 --> 01:00:13.000 He's walked you through a bunch of other stuff, you know, some fundamentals 633 01:00:13.000 --> 01:00:15.800 on stimulus and stuff. And yeah, a lot of it I knew, 634 01:00:15.840 --> 01:00:19.679 but some of it I wasn't as familiar with. And it's been really really 635 01:00:19.719 --> 01:00:22.920 fascinating to work through it and at the same time, you know, kind 636 01:00:22.920 --> 01:00:27.119 of get a better handle on some of the things where I had kind of 637 01:00:27.199 --> 01:00:31.679 muddled my way through and now go, oh, okay, this is this 638 01:00:31.760 --> 01:00:35.000 is how this works, and so this is the way that I ought to 639 01:00:35.000 --> 01:00:37.679 be doing it. And sometimes I disagree with his approach, but it's been 640 01:00:37.760 --> 01:00:42.760 really fascinating to get through it. So I'm gonna pick The Rails and hot 641 01:00:42.760 --> 01:00:45.840 Wire Codecs. It's about one hundred dollars. It's an ebook that he put 642 01:00:45.840 --> 01:00:53.679 together. And then I got back into The Walking Dead. So several years 643 01:00:53.719 --> 01:00:59.719 ago I watched the first I don't know, five seasons and then I quit 644 01:00:59.760 --> 01:01:04.079 watching it and they've put out like eleven seasons and they have like five spin 645 01:01:04.119 --> 01:01:07.239 offs, and I was like, I really liked that show, so I've 646 01:01:07.239 --> 01:01:14.920 been rewatching it. So I'm going to pick The Walking Dead, And yeah, 647 01:01:14.960 --> 01:01:19.199 I guess the other pieces is I've been kind of doing a rewrite of 648 01:01:19.320 --> 01:01:23.239 top End devs basically with a lot of the stuff I've been picking up out 649 01:01:23.280 --> 01:01:29.000 of the Rails and hot Wire Codex and I have to say I am very 650 01:01:29.119 --> 01:01:31.239 very happy with Tailwind and Tailwind UI, So I'm going to pick those two. 651 01:01:34.639 --> 01:01:38.719 All right, Viat, what are your picks? So, yeah, 652 01:01:38.760 --> 01:01:46.519 sure, I really struggle maintaining focus while reading books. So my first pick 653 01:01:46.719 --> 01:01:53.880 will be Speechify, which is AI based text to speech application, and that 654 01:01:54.079 --> 01:02:04.320 helps me read more. It's high it's text supports like important ebooks and all 655 01:02:04.440 --> 01:02:10.239 that, so that basically might go to app for reading right now, Another 656 01:02:10.440 --> 01:02:17.559 peek will be Kagi Search. I hope I pronounced that right. It's a 657 01:02:17.599 --> 01:02:24.320 paid search engine, which is by itself already interesting and unusual. So their 658 01:02:24.360 --> 01:02:34.039 idea is that they are privacy first. And there is also a feature that 659 01:02:34.119 --> 01:02:39.000 I want to highlight, which is they have integration with different AI models like 660 01:02:39.280 --> 01:02:45.719 chudge Pit or Googles, Gemini and all that for twenty five bucks a month 661 01:02:46.360 --> 01:02:54.920 versus twenty bucks in JEPT for example. So they don't offer all the features 662 01:02:54.920 --> 01:03:00.760 from Judge EPT, like you can't use the leaf for example, for images, 663 01:03:00.559 --> 01:03:06.159 but still that's a great thing to use. I also love that I 664 01:03:06.199 --> 01:03:12.880 don't need to go from the search engine because that's my go to side basically. 665 01:03:13.360 --> 01:03:19.280 So yeah, and twenty bucks plus five bucks for a search engine, 666 01:03:19.320 --> 01:03:22.519 why not? All right? Well, if people want to follow up and 667 01:03:22.920 --> 01:03:25.840 find you on the internet and ask you questions or you know, give you 668 01:03:25.880 --> 01:03:31.920 feedback on what we talked about on your verbal API, sure find you. 669 01:03:32.519 --> 01:03:38.280 Yeah, you can find me on Twitter or x whatever you want you use. 670 01:03:38.840 --> 01:03:47.920 So it's ask creak of underscore depth and I'm ask creak of on GitHub. 671 01:03:49.360 --> 01:03:51.280 All right. Well, We'll have all that in the show notes. 672 01:03:51.480 --> 01:03:53.440 Thanks for coming. This was awesome cool, Thanks for having me. It 673 01:03:53.599 --> 01:03:58.719 just it makes me want to go play with open API and the swager tools 674 01:03:58.840 --> 01:04:00.480 see what I can do with it. House up h