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