Hey, welcome back to another episode of the Ruby Rokes podcast. This week on our panel we have Valentino Stole and now I'm Charles Maxwett from top End Dev's. We have a special guest this week and that is swat. Do you want to just tell us you are? And sure? Sure? So I'm back at the engineer at Evil Mustians and I really love working with all the exciting technologies using Ruby eggs, like to make Ruby look like Golang. For example, writing barsers running Ruby was in browser with Ron Ruby, Don
Dev and Charles. You decided to bring me here to talk about API documentation, right that? Yeah, that's my favorite topic. I'm every week on the show. I'm like, we're not talking about API documentation. Why am I here? Let's fix that? Yeah, let's let's do it. So I have to say it seems like documentation is the thing that everybody just kicks the can down the road with. Right. I'm also going to point out so not this contract that I'm on. The contract before I was working on
some API. No, it was two contracts. Anyway, I was working on basically integrations between two APIs. Right, It's like, hey, get the information out of here and sync it up with the information over here. And I have to say, API documentation is a concept that some of these
folks could have worked on. Let me just put it that way. The people who documented the APIs, it's like it's like, okay, yeah, you're telling me all these fields, but you know, it doesn't actually tell me how to use it, right, And so I wind up trial and erroring my way through sending them a date or a string or you know the structure of the data I have to send back. So yeah, so how do we do it better? Yeah? So I was in the same position, and I was one that did that to you, not not to you,
but you know, two different developers with the poor documentation. So if you yeah partially, So yeah, let me just tell you tiny story that covers up like the whole my career, like the past ten years, and
I'm doing API APIs. So I started my rugby career in small healthcare startup and we had a simple rails API only application on the back end and two native mobile apps, so only three of us, no seniors, no rules, no documentation, and everything went pretty fine until we started developing fairly complex features, and quite soon we went to the developing features. Spread across three
different platforms without any API documentation is quite painful. So we started documenting our API using a new and heap app called postmon, so we might use that, and that saved my life on the scenario I was talking about, because I could rapidly go this, no, this, no, this, no this no, hey it worked, Oh it kind of worked this anyway. Yeah, yeah, basically that's what we did. So you can save those
actual like tries and reuse them later. So that was our documentation in the at the moment, and it went again pretty fine until I forgot to update it too many times so and our personal collection become constantly stale. And with that we discovered arthwag, and artwag is a gem that extends Arspec with a special DSL and uses that to generate and open API documents, which then turns into beautiful live documentation. And that's basically my dream came true because you know,
we generated something like postma collection right from our Arspec tests. That's a miracle, and we don't need to think about API docs. They're just there and always up to date. That's cool. So the resulting development process it looked like this. So I developed a Vizero version of a new API feature that we need. I tested that with artswag generated documentation and passed that to
mobile debs. Then they use the documentation and they implement their own interfaces, and sometimes they asked me to fix my API, and since it's rails, I do that pretty like quickly, right they need to rewrite tests when I do those changes. Was kind of irritating, but still it worked pretty fine until the time we decided to add a medication reminders feature to our app.
To support that, I designed a model that added to fields like start date and end date, and I made end date noble since for cases when reminders should never stop, because you know, medications. So with that, weeks later, I'm testing the resulting application, the mobile application, and what I'm seeing is a reminder with the end date in the year to like four thousand and one, which is kind of strange to see that and fast, Yeah,
apparently I was developer. Decided to mark those infinite reminders with a day distant feature like distant future, and that thing serializes to the year four thousand and one. Wow. Okay, since my biln deavs in my team they were better team players than me. They discussed that decision actually, and Android developer did the same. But in Java cyralized version become the year nineteen ninety
nine. Oh wow. So that was a sign that something went completely wrong with our workflow, right, And the problem is we had the documentation in place, and the end date was marked as new in that documentation. So and if you think about that, it's really logical to use like now for end date that is unknown at the moment, because it can be anything that user can add like date there and stop taking those medications like tomorrow or in two weeks or in two years whatever. So the now is like it's like
by the book, like it's like the description of Noll. And yet Mobile Deaths decided to do that horrible wrong thing. So but if you think about that, actually it was me who was wrong because my attitude towards the documentation was completely wrong. I thought about that as a like artifact, and I didn't write like proper description to explain why the end date is noble. And we never discussed that case with the team, or maybe we did, but
we lost that somewhere in the selector. So aarspect didn't help me to become a better developer. Thankfully, about the same time, I bumped into talk about the competation first approach from Reelsch twenty eighteen by Aeriel Kaplan, And after that I finally realized that the commutation is actually the core of my API and not just the leftover. So now I, honestly I can't imagine developing APIs in the other way. So let's take in this, like, what do
you mean by documentation first? Like, I know, you know, folks can listen to Aeriel's talk, you know, after this, because it is pretty great, But can you sum up just like, what do you mean by documentation first? Sure? So with the commutation first, you start your work by writing the specification for the resulting API. And that might sound like the most boring thing in the world, but actually that's what the best programmers
do when they design their code. Matz doesn't start with the implementation of a new feature for the language. He discusses the interface first, and in that discussion, that discussion itself, it might take much more time and effort than the implementation itself, And probably that's why we'll offer Ruby, and maybe that's
why we have next to none breaking changes in our language. So like another example, like imagine silently preparing a giant PR to bring something cool to your project, or say to open source project and say you prepared the PR for Rail's active model, like bringing something really cool and giant and awesome, and you opened it and you've got a review from someone from the core team and they say that, actually, you know, the resulting interface, it's not
in line with the Rail standards, Like we have all those different ideas already here and there, and they have like all the examples and clear action points for you. So it's not a rude no, it's an actional thing. But in the result, to get your PR accepted, you need to rework everything from the scratch. And I don't know, do you feel the pain right now? Because I definitely do what would be better to create an issue
and discuss an interface first rate. That's basically the documentation first approach. So let's let's give another example with an API, since we were talking about APIs.
So you are working on a new feature. You designed the models like services, commands, form objects, whatever you use, and you tested all of that, of course, and you pass the result to your team and Apparently you're like pagination, filtering, design whatever it went out of think with what front end needs, and for some reasons, they are locked to use
that specific format because of framework or vend or whatever. So it's your fault and you must to drop everything and all that beautiful, well tested, perfectly designed, re usable code that you did. You just need to remove that and start from the scratch. So maybe, like I know how many listeners screaming in again you right now that that would never happen to them. Like, but if there is no process, you might discuss oagination, but forget
about filtering or mids the fact that front end needs that specific interface. And so we are all just humans or martians and we need processes to guide us. Right. Another idea is a no one ever complained about my dogs, so they are good. Probably, Charles, you had your your story about documentation. Have you ever told the other side that their dogs are bad? Yeah? Cool? So in my situation, I worked in a company with
one hundred micro services and like four or five different service SID languages. In that structure, you're always a consumer and a provider of an API, right, So I saw what happening when someone uses those OUTO generated dogs with like this idea that it's a simple artified and it was just unusable, as you said, like it was just a list of function names instead of human readable descriptions, and it was just a silent list of hopefully all attributes and that's
not enough to work on. Uh yeah, in yeah, I just want to chime in there. I mean, this is the problem I have with like our doc as well and things like that, is like you've got some comment or maybe it'll actually scan the code, it's just yeah, you don't get the whole story, right. It's like, Okay, I've got a list of parameters and maybe an endpoint to hit or something, but it doesn't give me enough to know how it's meant to be used. True. True.
So in case, when it was Python on JavaScript on the other side, I was able to just open the code and read it instead of documentation and it was fine. But when it was Java or something else, I just started deeming developers because it's impossible to work with So voluntina. I know you use arspec, how do you use that? So do you document your your API? Do you use that? You know DSL extensively some teams use
it more than others. But yeah, it's use that a you know, URSPEC focused realm where the specs will basically you know, there's another side of this where documentation first is a nice API first you know design principle. Another realm of people also think test driven is also a good way of also documenting the code and processes, which may be not the best case for all API design. Ah, but yeah, it's definitely more test focused than it is
documentation for cool cool cool. So actually, you I met people who do artsqac. Do you use artsquac extensibly? Like they you can write beautiful documentation with arsuac, But there is other side, like do you, like, can you ask your front end team to write those artsquac tests for you? Or maybe in that case when you work in the company with a lot of backends tacks, are you ready for some parcel tongue developer to write your tests for you? I'm sorry, but I'm not, so let's use yama instead.
So yeah, the commntion docummuentation first, or you can call it specification first, scheme first, design first, whatever, it's all about that. It's all about bringing the process to your workflow. It will not work if you just silently write a giant yano first and then write the implementation all by yourself. There is no communication. So it might be still better because it will work Like TDD, you think about interface first and then implement it.
But still it's all about communication and your documentation. It must be the central tool of communication with your teammates, with your clients, and for external API consumers. Your docommentation is your product. When you develop a feature and forgot to document it, you just wasted your time, right, no one ever find it that closed code, even in open source, like one percent of users will open your code and read it actually and try to find the feature
that will never mention, like what was never mentioned? That's cruel, but you know that's true. So with that, I hope I sell the whole idea of the documentation first approach, Like we write docummentation first and we can move forward towards you know, technical details next. Yeah, the technical details is kind of what I wanted to dive into. I mean people have done
TDD. Yeah, you get that thought process ahead of time, you know you're putting together and yeah, I really like the way that you put it where yeah, your API is your product because for a lot of consumers it will be. So let's get into the technical details then, So how do you do it? Is like reading driven development. You've been mentioned our swag a bunch two sure, so our swag is call first, not call first,
test first, I guess, but not the documentation first. For me, at least, you can do that the commutation first, but it's still much harder to write ARSPEC. Then right, then it's right to write YAMO files because you can use editors like and everything. And again YAMO is understandable by other teams as well, so even your like manager can read the YAMO I guess, especially in the editor like Swagger editor, because they can read
the documentation like the results in the commentation from the start. So hold on, so you're saying to write so you can write it in an r swag format and this is just coming from me not having used it, or you can write it in YAMEL. So yeah, let's sart come back a bit. So in the documentation first, the whole idea is that you have this standard, you have this you know, document that describes your API and in
our realm, like with RESTful APIs. That standard is open API. And by the way, Ruber Rocks has an episode about open API with Josh Bonalat and I think we will live a link to that episode in show notes. So Josh also wrote a book about open API, and to me that book actually looked like four hundred pages of design first. He called that design first
Workshop. So if you want to really dig dive into that topic and see how it works, like in four hundred pages, you can check his book out because he does a great job giving a very detailed description of the whole workflow. But yeah, so we have this standard open API, which is a strength standard for describing rest foolish APIs. And the resulting document is a
Yama or a Jason file. It contains descriptions for all your requests responses at leasts like HTTP methods, us quarry, params, headers, body attributes, whatever all that you need. Right, So that's our center of tension, that file, and next you can the way you will generate it, the way you will get it file. That's a different like approaches you can work
on. For example, you can use arswag, which uses metadata from your request tests and also adds a special DSL to for descriptions and all that stuff. So as a result, when you're on your tests, it also generates the file that open API file for you. Or you can obviously just write it manually and there are plenty of editors and yeah, you can do that
as well. So this is something you can write ahead of time, right, It's not something that just because because you were saying, you effectively, you know, write your stuff ahead of time instead of like I said, I'm kind of imagining something like ar doc where you know, it looks at your code, reads the comments, but even if it inspected the code. In this case, you can just write our spec tests or things like that in order to say this is how the API should perform, and then it
generates the documentation from the DSL. Is that is that what we're looking at here? Yeah? Ye, but it's your tests and not from your and not from your code or whatever. So if you haven't implemented yet, fine true yeah yeah, so yeah. There is also a way to generate open API from your code. So there are helpers for controllers and all that. So there are different approaches. The problem with those approaches like when you, for example, use code like DSL in your controllers. Obviously you need to
write the whole thing. That's a problem. When you you can move that to tests, now you need to write your tests, which is also sometimes problematic. You still need to bring all those models and all that. So even less hard to maintain approach for me at least is writing the whole specification first at SAMO. Yes, that's that's that might be a problem, but a like, at the same time, you can read it. JavaScript developer can read it. Everyone can read it, So I don't I didn't.
I don't know if JavaScript developers speak yamal. I think they speak Jason. That's also the same format. So right, So so what's your whole process then? So you sit down, you write out the specification, you poort that into a test with our swag or do we even do that? So yeah, if you go my way, which is writing the YAMO first, then you just open a PR for example, and discuss that documentation with your team, with your stakeholders whatever, and they all can see what is happening.
You can bring like you can get like really fast answers and gain the information that you missed while doing that. So that's the first step, and then you can get the resulting file and start developing your part, and front
end developers can start developing there for part. So it's also like you can work at the same time, which is a great feature regarding the Uh, just real quick, while you're developing the spec, are you saying that that is like made available for people to kind of play with, like in a UI kind of way. Sure you can generate like if you set up a PR like CI to watch your PR and to develop like deploy docommodation, why
not. So that depends on your workflow. So yeah, so just yeah, just to kind of dive into this a little bit, So you generate the AML, so does it generate the spec for the specs like the RSPEC specs for you or do you still have to write those separately. So yeah, in my case, I wrote a JAM that called Schuma, and that jam adds like three or four helper methods to arsvac or mini tests to your
request tests. So to test your request against the specification, all all you need is to prepare the request, call it, and then write something like assert the specification or it depends on the framework, but like it is expected to conform schema the code of response that you are looking for. That's it,
like one line. With that one line, you are like, you will test all the headers that you write in your documentation, in your specification, all the attributes, body attributes like request response, all that with just one line. So that's that's a great way to clean up your tests.
I guess, yeah, that sounds awesome. So then so then you just go and implement, right, So then you're writing your your API through your controllers or I saw in your article you're using great API, which I may ask you about in a minute, but yeah, as a way, yeah, yeah, I love great API and I hate great API. So anyway, it's yeah. So so that that's pretty much it. So you're you're you've got your documentation then in Yamel, and you've got your tests that run
and things like that. So I guess the other thing that I'm wondering about here, because there are some benefits to open API, right, yeah, I'm pretty sure you can. You know, if you have open API compliant documentation, then you can import it into Postman and things like that. And if you haven't tried to Postman, you should. It's it's a terrific tool.
But I guess my question is what about written documentation Because to a certain degree, yeah, just having it pull up and say, you know, yeah, you're going to send this kind of a request, You're going to get this kind of a response, You're going to see this kind of behavior you know on the other end. But sometimes you need a little bit more
than that. So how how far does this get you? As far as, like you said, the API being the product, how far does this get you as far as somebody like me coming along and going okay, how do I talk to this app and being able to get the information I need out of it without necessarily being able to read the YAMO file or being able to see it. Sure, So open API allows you to extend itself,
like with special X keywords. So all of those generators, like the commendation generators, they come with those special key words that you kind of use to generate like a special pages and use and mark down to explain everything you want. So there's also the idea that you can tag use tags to your requests
and also add a description to your tag. So for example, you come to users tag, it's like a big chunk of your documentation and you can put marda on there and just kind of explain everything about users you want. So, yeah, that's all available there. So I'm curious what your approaches
for like, you know, sample data. You know how that's definitely one of the like hardest problems I find with even document documenting specs, right, Like it's how do you fake the data in a way that is also like accurate to the usage, right, Like you can't just like sample production data all the time, and so like what is your approach for that? And then maybe how does like the opening having it as a separate specification, how
do how does that help you know in that process? Right? So to me personally, I was interested in that at some point, but then it wasn't needed on other like projects, So I'm not currently you know, up to date here, But there are different ways. For example, there is an issue in SCUMA two allow such like interface for adding examples from the test data, like providing that and adding that to the specification. I hopefully will
come to that issue someday. So another thing is that, like what's the issue that you want to fix if you want to fix the problem that your example data might be out of think with the rules that you described, there are like plenty of tools to date that because open API it's a common standard, there are like different languages and different tools. You are not scoped to Rugby only tools, so there is like a lot of tools for almost every idea and thing to do. So yeah, I don't remember the name for
that tool, but it's definitely there. Yeah, I mean, just as an example, I think of your you know, original use case where you had the end date that was like to infinity. You know, like, how do you, like, how do you even model that from a fake data perspective? You know, how did you in this case like document or maybe not even document, but specify that in the specification. The specification allows you to use. It depends on the version, Like if it's version three
point oh, you can say that it's noble true. And if it's like more common like the current version three point one, you can use array of types. I guess that's something that you can do. And yeah, that's by the way, that's painful because if you will write now without like not as a string, that will be now the data not the string, which is painful. But anyway, so yeah, and in that case, I don't think you can do anything, but just using your plane like English,
to just describe what is happening, because that's what the commutation does. Probably you can read the commentation that contains only examples, right, that's a strange recommentation like rails guides and there is just a list of you know, you know there is a site with like something in fifteen minutes or something like that, like different languages and all that. That's just one big chunk of example.
Yeah, that's that's you can use that. But so when you're designing APIs right, So let's say you you're like, all right, you know, I need an API for my application, and I'm putting it together, and you put it out for feedback from your coworkers or you know, maybe customers or whoever. Right, what kind of feedback are you generally looking for?
And how do you prompt them to give that to you? Because I swear like half the time when I ask for any kind of feedback, like in a PR or something, it's just like, yep, that's good, right, So and I want real feedback, right, It's like, no, we don't do it that way, or this would make this easier on me when I'm building some other thing, right, Yeah, so I don't know like that feedback. It sounds like the feedback from people who are not
interested in the result, you know. And I don't mean like in the rude way. I mean like, yeah, that will be fine. I don't really care because you will make it work, right, I do understand that you will do that. But in API, that's an interface that will be used by those people, so they kind of they want it to be easy for them. So maybe they already have thought about some edge cases in
the UI or something like that. Again, the pagenation is a great example because for example, they want to use like infinite scrolling and they can use like cursor pagenation, or they want to use pages and you did the crystal opagenation and it's obviously not that something that they can use. So yeah, okay, yeah, well I'm kid. This makes me think. So I'm
in graphicoll a lot. That's what all of our clients use, and it makes you think, like, of I love it, but it makes it does make me think, Like, you know, a lot of times you'll have the front end people separate from the back end and you'll have the same stories kind of working in parallel, right, like where somebody will be working the interface and somebody will be working in the back end stories, and you'll race kind of like you know, to make sure that the you know,
front end team can align with the back end, but also like that you're supporting everything that they need. And a lot of times people will just like make you know, fake wrappers of what they might expect to need, you know, in order to build whatever they're building. You know, what what is your like where does that uh you know, specification aspect fit in that kind of workflow where you know people need to use it right away and the
specification gets molded kind of as it's getting worked on. Yeah. So the great thing about open a BA is that you have mock servers for example, so they can use them and you don't need to touch a keyboard for that, so they will have their more data and you don't need to like do that yourself in the back end code. Another thing is that it's fine to
get back to the specification. Uh, it will happen like all humans, as I said, so, yeah, but the probability I think is my you know less, it's much less common to go back and fix something if you already thought about that in the first place. So Valentino brought up graph ql, and I have not talked to anybody about open api for a long time, and I haven't really looked at swagger open api for a while. Does this work on systems like graph ql or is it only like rest systems?
So right now it's only rest systems, and it's it's even hard to implement, like describe something like RPC because that's just one end point and just what open api looks like that doesn't work with such cases. There is a new version, like the version four point zero Moon Bulk. I guess it's it's it's called so in that version they do might like they try to support such cases when you have one end point and a lot of different like actions.
So I don't think that graph kill is like interesting for them because it already has the scheme and all that. But yeah, those cases with when you use just one end point and a lot of stuff happening in there because of like I do you know, like different headers or very prims. That's what they try to fix in the new version. So one other thing that I think would be good to cover for folks is we've used the terms open api and Swagger interchangeably. You want explain what they are. I don't know
about you, but I didn't because that's different things. Actually, okay, I may have used the Yeah. So Swagger is a company that developed the first draft, like the first I guess, a couple versions of open api the thing and called that Swagger at the time, and they decided to like they were cured by another company, I guess I don't like something beat.
Sorry I don't remember the name, but anyway doesn't matter. So they just decided to make it open source, the whole specification, and then they renamed it to open api and made it public. I mean, like open source and Swagger that name they decided to keep and name their tools with that name. So when you talk about Swagger right now, you probably refer to their
tool in like Swagger UI, Swager Editor, and so on. Okay, so all of this, uh, you know a p I automation and schema documentation just makes me think of function calling uh in the AI realm uh are you are you using this uh kind of methodology to like for code generation purposes or for like augmenting you know, AI workflows and stuff like that. So uh, as I said, I prefer to write open API dogs manually. So yeah, in that case, something like uh copilot, it helps a
lot to write them. Uh so. But regarding code generation, actually there are generators in the open API realm. It's not about AI. But anyway, since we are talking about that, you can generate client side as the case, which will include validation, cerilization, all the good stuff. You don't need to write that. And like, there are different languages and versions.
There is even version for Ruby, and they even have SDK generators for server code, so you can generate your server I don't know of any Ruby gems for that, like Ruby generators for that. But still if you want to generate gaoscript something, yeah, you can do that. So yeah,
I don't know if I answered your question. I was just looking at your Schuma Jason stuff where it validates the schema and that's very much kind of like what function calling does when you're working with something like open AI, right, So I'm just curious if, like you were, you were using it maybe for that purpose in the Ruby side. Now no, I may, I
may try it out. So Jason Scoma is another gem that like implements another standard that is used under the open API, So when you describe different arm things in open API, it might be like quay, parameters, body, whatever you use. Actually use Jason Schema. In version three point zero, it was like subset superset of Jason Schema, which was painful for everyone.
So with version three point one, which is the current question of open a PA, they first of all they upgraded the version like for five major releases of Jason Schema, which is that's a different story. But yeah, they also made it like the standards so you can use that and yeah, that's
that's a great tool actually for foundation. Yeah, it's funny. You can you can pass schemas uh to you know, these large language models, and it knows how to adhere to it even without like the function calling aspect, which is kind of interesting. Yeah, So I'm curious like now that you have like this documentation first like approach, like how do people like it on
your team? Like is it is it like everybody's excited about it or is it like kind of a struggle to get people on our people still hesitant? Like how is it working out? In depends? It depends. So for example, what Polkan he heads it, I guess, I know, like writing something manually without DSL. He just but you know, the approach. It's good for small teams if there are different stacks, but if you work
in a full stack team or something like that, that's overkill. Basically, if you don't need to discuss those APIs or for example, uh Inertia Jazz, you can use that to just eliminate the whole AP I think from from your application because I don't know if you know about in Airsha, but it's a geoscreet library. Plus it has plug ins for for example, rails and
for different front end frameworks like React view as well. Yeah, so when you use that in your application, you just replace your view files with whatever framework you decided to work one, so for example with React, and there is no API for that, so it's just like passing the whole bucket of data just renders that. So yeah, you can remove the whole API thing from your application and yeah, no need for manual yamal writing. Yeah. I think it even works kind of like in an SPA style of app too,
which is interesting. So is there anything else that we should know about
with open API and Swagger and all that stuff. Yeah, I know, like if you use open API to document things, whatever you use like ARSWAG or SCUMA or whatever, please dig deep into the tooling stuff that they have, because it doesn't matter if you generate your documentation with ARSPAC for example, you still can use all those tools to for example, link your API documentation and with open API your API it becomes I know, you can touch it,
right, it's a whole new experience because that's that's something real. And since it's real, you can lint it. You can use static analyzers on that, and you can, for example, you can use tools to catch like some errors or for example all WSP problems with security all that. So, yeah, that's really powerful idea and please please play with that. You
can use linters. You can force everyone to add descriptions to artifact using those tools because you can use linter and add that to CI and yeah, that will blow up unless someone did their work properly. Nice. It sounds like what you're saying, there's there's no excuse for for API documentation. Yeah yeah, oh but I like my excuses. They make me comfortable being lazy. Do you do you create API documentation for like side projects and just one off
things that you're trying out. Ah, that's such a painful question actually because all my side projects they have more like gems and a logical thing to do, Like why not document your gems first? Right? Like right, no, No, my gems has next to zero documentation. That's so painful.
You asked that. That's so rude, Like we're almost almost done with the podcast and you yeah, we never would have known, to be honest, Like I'm curious about this question, right because like, uh, you know, why don't you Why don't we like have this creativity and like experimentation like with a documentation first thing, like what is like the barrier from us like thinking about our ideas in a specification way versus like where we're trying you know,
Like, I don't know. It's a it's a question I think about a lot. That's all about like the talk that I told about from aeral kaplan. It's all about that that you are. You can write that documentation upfront because you have to, Like you are so energetic at that moment you
are like creating stuff and it's it's easy. You you want to like understand it yourself, and you think I will, I will do that way or that way, and I need to fix those edch case and you know at that moment, that's just when you can do that after like after you did the all work. It's just like describing all that and it's the worst part.
Well, it's funny because not just documentation, but in other areas, right, I mean, I still see people that and I've gotten out of the habit of writing tests right, or writing good tests, or you know some of the other code hygiene things that I do on the front end that I know I should do right. And so it really just comes down to, I mean, not even whether or not you believe it or believe it to be a good thing or worth your time. It's a matter of discipline.
And it seems like a lot of this stuff just comes down to discipline. Right. Are you committed to writing the best coach you can? Are you committed to delivering highest quality product you can? Right? I mean, obviously as you approach perfect it takes more and more effort to get it, you know, to get more quality out of it. But you know, are you committed to putting out stuff that just you know, ticks all the boxes on stuff that is maintainable? Right? Because we're not talking about.
Oh, you know, I'm going to write this documentation so that I can pat myself on the back. I'm writing this documentation because I know that it'll make somebody else's life easier, right, I know that it'll make it easier to maintain. I know that it'll do these things for me. And so it really is down to discipline and whether or not you're willing to do the sometimes tricky stuff in order to make it work. But the thing that I found, too is that the more I do those kinds of things, the
better off I am because my skill level goes up. Right, I can more easily tackle more difficult problems because I've done the discipline then to write to make sure that my documentation is up to date, or to make sure that my tests run and pass and that I have decent test coverage, or you know that I am breaking up my huge models or giant controllers or whatever other thing right that I know I should do. I'm doing it because it makes
a difference later later on down the road. So anyway, I'll get off my soapbox. But the discipline questions, one thing that I like to hit is, you know what you're supposed to do. You doing it the processes. The processes can help you also, like links, Yeah, just just turned on the lint that like what it was like the linter that tells you to write five lines of code that months for a Oh right, well I don't always agree with But the thing is is that you can, like with
rubocop, you can make it whatever you want it to be. Right, So you can tell it no, I'm okay with ten line methods, right, or you can just turn the rule off if that's something, or maybe it just check it, check for egregious stuff. If it's fifty lines, then I have a problem, right, I don't know, but yeah, getting into it, it's like okay. And that's the other thing is is I think people get into the mindset of my documentation has to be perfect the
first time or right, or you know, the linking rules. The linking rules have to be exactly what I want. Sometimes you have to fuss with it a little bit in order to figure out and it's not even to get what you want, it's to figure out what you want so that you can have it right. And so it's you know, five lines of code and a method is way too restrictive, right. I just I find myself frequently needing eight right, so I'm gonna bump it to ten right. Totally fine,
go to ten right, not hurting anybody. But you know a lot of times those are the other excuses that we used to not do the stuff that we know we are to have in place. The cool stuff about like all those splinter rules that you can, yeah, turn on all them, but that's an opt in action. You need to think about that. Why
can I do that? It's like strong migrations jam that allows you to ignore all those rules, like you're trying to like break and you know, add a new index for example, to the table, and it yells at you like, hey guy, that that will be like painful, there is too much data. But you know that it's like ten lines of like ten rows, so you can do that. So it's all about that, you know, thinking yep, I don't want to think no. I think I'm curious, like how how all of this will pan out in the long run.
And it makes me think of like, you know, things like you know co pilot or something like that, where you know you're just documenting things and then it just fills stuff out and it'll it'll be interesting to see how those kinds of developers evolve over time and and hopefully like you know, the auto documentation test aspects of it just like happen. But but I don't think we're
there anywhere near term. But I do think about like you know, Gary Bernhardt's like original destroyeral software stuff, and when I was getting into test, you know, for the first time and just seeing that like workflow, like he's just wild, like, oh yeah, let me open up a test so I can make sure that this thing works right. And like before he does anything like no codes written right, like and it's like, okay,
I want it. I describe basically it's documentation, right, I describe how I want this thing to work, and then I go make sure that it works right. And that's definitely a very like it's a shift in how like you're kind of taught like coding wise, where it's like all right, just
go try to do something right. And I think that's maybe why we have a hard time in our side projects like documenting things, is like we just want to go try it right, and we just want to like mess around with stuff, and maybe we need to like veer away from that like thinking and learn how to mess around with things in a more controlled way. Yeah, there was another wild idea, like I think it's from then when when
he was in soft boats. So it was idea that he will just remove all non committed code like once for a while when so when he work on something, he gains more information, he knews what he wants to do, and if it's not committed then it's okay. He will just write it again and it will be better. Something like that. So yeah, not another extreme idea. Yeah, was it Toby Luke from Shopify. He's notorious for doing that, for just like nuking his entire you know, stuff that hasn't
made it and just rewriting it again. And I forget what. Yeah, there was a there was a stuff like that. Yeah, I forget what they called that. I think it was red green. And then there was something else and it was basically you throw the code away and do it code
away. And I can't remember what he called it, but yeah, I mean, I don't know how many times I've like gone and done code and then had just like it disappeared because I committed the wrong thing or like missed something or rebase right and they're like, whoops, I don't know where that went. And then I just like rewrote it and it was good. So it can be good, but it's frustrated. All right, Well, let's
go ahead and get into the picks. Oh it's it's uh, it's TCRs, test and commit and then revert or test and then commit to revert and so if it's not good enough to commit, then you revert and do it again. Anyway, let's do picks. Let's let's uh start wrapping up Valentino. What are your picks? So, as my recurring trend seems to be, I have a lot of AI picks here. One is called udio dot
io udio dot com. Sorry. Uh. It's basically a really awesome uh ai music generator where you just give it a prompt and it generates like incredible songs. This is wild. But it also lets you like focus on either just like the instrumental aspect or you can break it out and I've been messing
around with it's so much fun. My other pick is uh I came across I've been playing with Allama a lot lately, which is if you're not familiar, just lets you try out a bunch of different large language models that are open source and available, and I came across this project called lit GPT, which basically is OLAMA but with the ability to pre train and fine tune, and it adds a bunch of those aspects of large lange model development on top
of it. And so I've been messing around with This is a lot of fun and it makes it super easy to get started with all that stuff. So I'd recommend checking that out. Very cool. I'm trying to pull together some stuff. Maybe I shouldn't announce it before I have it ready. I'm trying to pull together some stuff to put together an AI and Ruby summit and just bringing people who are working on all this stuff because it seems like there's
a lot and it's very very interesting. So anyway, I don't have dates or anything or even know who this speakers are, but yeah, looking at that. My picks, I usually start out with a board game, and I'm just I'm not thinking of a board game I really want to pick, so I'm going to pass on that. I am going to pick. If you haven't read it yet, folks, I Usuh, who's one of our other co hosts, he wrote the Rails and hot Wire Codex, and I
decided, you know, because sometimes I how do I put it? I guess in the past the way that I've learned things is just by kind of I need this, I need it to do it, and so I'm going to go find the way that it gets done. And he kind of walks you through the process of doing the things that you're you know that you're looking
at there. And so I'm about a quarter of the way through the book at this point, and so far, he's walked you through building your own authentication, He's walked you through through setting up Turbonative for Android and iOS. He's walked you through a bunch of other stuff, you know, some fundamentals on stimulus and stuff. And yeah, a lot of it I knew,
but some of it I wasn't as familiar with. And it's been really really fascinating to work through it and at the same time, you know, kind of get a better handle on some of the things where I had kind of muddled my way through and now go, oh, okay, this is this is how this works, and so this is the way that I ought to be doing it. And sometimes I disagree with his approach, but it's been really fascinating to get through it. So I'm gonna pick The Rails and hot
Wire Codecs. It's about one hundred dollars. It's an ebook that he put together. And then I got back into The Walking Dead. So several years ago I watched the first I don't know, five seasons and then I quit watching it and they've put out like eleven seasons and they have like five spin offs, and I was like, I really liked that show, so I've
been rewatching it. So I'm going to pick The Walking Dead, And yeah, I guess the other pieces is I've been kind of doing a rewrite of top End devs basically with a lot of the stuff I've been picking up out of the Rails and hot Wire Codex and I have to say I am very very happy with Tailwind and Tailwind UI, So I'm going to pick those two. All right, Viat, what are your picks? So, yeah,
sure, I really struggle maintaining focus while reading books. So my first pick will be Speechify, which is AI based text to speech application, and that helps me read more. It's high it's text supports like important ebooks and all that, so that basically might go to app for reading right now, Another peek will be Kagi Search. I hope I pronounced that right. It's a paid search engine, which is by itself already interesting and unusual. So their
idea is that they are privacy first. And there is also a feature that I want to highlight, which is they have integration with different AI models like chudge Pit or Googles, Gemini and all that for twenty five bucks a month versus twenty bucks in JEPT for example. So they don't offer all the features from Judge EPT, like you can't use the leaf for example, for images,
but still that's a great thing to use. I also love that I don't need to go from the search engine because that's my go to side basically. So yeah, and twenty bucks plus five bucks for a search engine, why not? All right? Well, if people want to follow up and find you on the internet and ask you questions or you know, give you feedback on what we talked about on your verbal API, sure find you. Yeah, you can find me on Twitter or x whatever you want you use.
So it's ask creak of underscore depth and I'm ask creak of on GitHub. All right. Well, We'll have all that in the show notes. Thanks for coming. This was awesome cool, Thanks for having me. It just it makes me want to go play with open API and the swager tools see what I can do with it. House up h