Cup o' Go

★ Support this podcast on Patreon ★

Creators & Guests

Host
Jonathan Hall
Freelance Gopher, Continuous Delivery consultant, and host of the Boldly Go YouTube channel.
Host
Shay Nehmad
Engineering Enablement Architect @ Orca
Editor
Filippo Valvassori Bolgè
Sound Designer / Audio Editor based in Milan

What is Cup o' Go?

Stay up to date with the Go community in about 15 minutes per week

Shay Nehmad:

This is Cup o' Go for October 25th 2024. Keep up to date with the important happenings in the Go community in about 15 minutes per week. I'm Shay Nehmad

Jonathan Hall:

And I'm Jonathan Hall.

Shay Nehmad:

And I am wearing the Cup of Go t shirt. Woo hoo. Hashtag not sponsored. Actually, these guys are not paying me. Actually, I just bought this with my money.

Shay Nehmad:

This is comfortable. We're recording this. We're doing the cheat thing where we're recording the episode, one day in advance. It's actually 24th. Don't tell anyone.

Shay Nehmad:

And this is gonna be my pajamas. So comfy. You look comfy yourself with that jeans jacket. That's a style I haven't seen in a while.

Jonathan Hall:

I'm sitting here

Shay Nehmad:

I'm sitting here next to the motorcycle crash. Exactly.

Jonathan Hall:

I'm sitting here on the balcony, overlooking Guatemala City. It's a little bit chilly, so I'm wearing a jacket, but it's, a nice day.

Shay Nehmad:

Chili? I thought you said Guatemala. Alright. If we're talking about places that are chilly, let's talk about Helsinki.

Jonathan Hall:

That's a nice day.

Shay Nehmad:

I'll stop for a segue. Here

Jonathan Hall:

you go.

Shay Nehmad:

Alright. Let's do meetups.

Jonathan Hall:

Yes. So, Helsinki has a meetup coming up on the 6th November if you're in that area. And, of course, you are because it's such a highly populated area. Then now you should check it out. So, one of my acquaintances from the Go Amsterdam, meetup is presenting there.

Jonathan Hall:

I I guess he's from Helsinki. I'm pretty sure he is, and he's back there. Had been in Amsterdam for a while. And he reached out to me, after our call for meetups last week on the show and told me about this one. So go check that one out.

Shay Nehmad:

Hey. 1,600,000 people in the metropolitan area of Helsinki. That's at least what Google is telling me. Nice. Other than the fact that it has people, which is required for the meetup, The topics look pretty cool.

Shay Nehmad:

Full stack with go and graceful shutdown in go to useful talks. Very cool.

Jonathan Hall:

Graceful shutdown is always a fun one.

Shay Nehmad:

It's always more difficult than you think. Yeah. You always figure out one extra thing you might wanna do and how long does it take and all the trade offs and channels and blah blah blah.

Jonathan Hall:

Oh, you mean I should flush my logs before I exit the program?

Shay Nehmad:

We have a thing at work that does has a scheduled job. Right? Every, like, an hour or so it analyzes something. I don't wanna get into the weeds. And it gets, like, a timer channel and the main context of the server.

Shay Nehmad:

Right? Do you think that when the context is done, we should run the analysis again? Because we don't know when the next, like, pod is gonna pop up. Because theoretically, if you have a crash loop that's 59 minutes long, you're never gonna do the analysis. Right?

Jonathan Hall:

Alright. I love corner cases.

Shay Nehmad:

We decided to to do it. We decided to go ahead with this update. It's a thing that checks, flaky tests and then sends messages to the relevant teams to let them know. We decided to do it even though it means the pod is gonna take longer to shut down. It's gonna be called the cluster slower.

Shay Nehmad:

Just the fact that we had this choice, very cool. So if you're into graceful shutdowns, fly out to Finland, I guess. Pack a coat. Mhmm. I don't know.

Shay Nehmad:

October in Finland sounds a bit rough. And actually the meetup is not on October. Right? I just missed that everybody.

Jonathan Hall:

Yeah. Yeah.

Shay Nehmad:

November 6th. Even colder. And if you're, into warmer weather, there's Gophercon EU. AU. Sorry.

Shay Nehmad:

Australia.

Jonathan Hall:

The gold version.

Shay Nehmad:

When is that?

Jonathan Hall:

So that's, also November 6th through 8th. So, you you do have time to hit Helsinki and then fly over to Australia for the last day of the conference, I suppose, if you really, really wanna.

Shay Nehmad:

So, I saw on LinkedIn 14 days to go. Dave Cheney is giving a session. Things I find myself repeating about Go. I saw that on LinkedIn. You definitely wanna make it there.

Shay Nehmad:

And you don't have to I'm I'm not sure which day of the conference it's gonna be so maybe if you're flying in from Helsinki, you might be able to do it, but I wouldn't do it like that. I would just pick 1. Helsinki sounds good if you're into graceful shutdowns and if you're repeating yourself a lot of times ago, maybe fly out to Australia. Or more realistically, if you are in Australia or if you are in Helsinki, go to those meetups. So let's do some proposals.

Shay Nehmad:

We we had a bit of a dry spell last week. Yes. But we have 3 new ones. We're not gonna discuss them all. Some of them are gonna be left in the bottom of the backlog, like your ticket about, you know, oh, yes.

Shay Nehmad:

I'll fix that bug. I promise, boss. But how about you tell us about the one that I am excited to learn about because I don't know this flag and it sounds really interesting.

Jonathan Hall:

Yeah. So this is a likely accept proposal. It's about enabling go cache prog by default. You probably didn't know it was even there as an option, let alone not the default, but, it is, Go ahead cache prog was added in Go 121 as an experimental feature. So this proposal is about making it available for everybody, so you don't have to run go experiment equals go cache prog to use it.

Jonathan Hall:

But what is go cache prog? Well, I'm sure you know that, Go uses a cache. Right? When it builds things, it caches the intermediate steps, you know, builds each package and caches that. That's one of the reasons that Go is so fast at being, compiling because it only recompiles the stuff that's actually changed since the cache has been created.

Jonathan Hall:

Right? But have you ever noticed how annoying it is sometimes, like, if you're using GitHub actions that, if you want to take advantage of that cache, you have to do all this work to, like, cache that on a disk somewhere and then create a tarball and then send that tarball to GitHub and then do the reverse before you run the next one. Right? You've seen that before?

Shay Nehmad:

Yeah. You have to, like, upload artifact, download of artifact. And, honestly, sometimes the build is fast enough when the project is small, you don't set that up. Yeah. And then, like, it it slowly creeps as the project expands and you might not notice that you're just wasting a ton of time and money in in CI.

Jonathan Hall:

Exactly. And then and then you get to this point, and then there's this this point on a lot of projects where restoring and creating that cache takes, like, 90% of the time of your of your pipeline run. And then an actual compilation and running your tests is, you know, 2 milliseconds, but you spend 10 seconds setting up your cache. So that's kinda what this is an aim to to solve is it lets you set a a cache program with this command line. So go cache prog once you pass in the name of a program that will do that caching for you.

Jonathan Hall:

So rather than the go command talking to the file system, it will talk to this program over standard input standard output. And then that program can handle caching for you. So you could talk directly to the GitHub API for caching rather than going through the step of downloading the cache, untarring it, and then retarring it and uploading it. You could just talk directly to that API and save a bunch of that intermediate work and make it a lot faster.

Shay Nehmad:

I I might be missing something, but very basically, the data still has to reside somewhere that's persistent. Because GitHub CI runs, even if you're using self hosted runners, normally are not, like, on the same machine that's, like, quote unquote dirty. Mhmm. They get at this point, even though, call me a heretic, I'm not sure it's a good idea, but most CI runs expect to start on, like, a fresh new newly born docker image of of runner.

Jonathan Hall:

Mhmm.

Shay Nehmad:

So does this do the GitHub API thing for me? Because if that, that's that's awesome.

Jonathan Hall:

It doesn't directly, but then you could have a program that does. Oh. Or you could have a program that talks to Redis or something. So you have a a Redis base to go cache or or whatever. You know, your cash could be anything at this point rather than the file system.

Jonathan Hall:

So that that's the idea. It gives you a lot of flexibility. I'm looking forward to, GitHub actions, not the service, but like an action. A GitHub action action, that does this for me automatically. So I get that benefit just by updating a version from v 5 to v 6, whatever.

Shay Nehmad:

This is super cool. The amount of investment and obsession about Go compilation time for the Go team is, very cool stuff. Good developer experience.

Jonathan Hall:

So this is likely except right now if you have an opinion and wanna weigh in. Now is your chance to hop over to the issue and, leave your feedback.

Shay Nehmad:

I assume the best thing to do, like, if you're interested in this or you wanna contribute, is turn on the experiment flag. Right? Right now. Yep. And then if it borks up your compilation, you should probably go to that thread and it's, like, the final comment period is the, like, the thing that happens in weddings and movies.

Shay Nehmad:

I don't know, by the way, if it happens for real. Maybe you can tell me because I've never been to a Christian wedding. Where that is if someone has, an objection. Right? Yeah.

Shay Nehmad:

The priest says, someone has an objection to this man and we're like, someone has an objection to this proposal, speak now or forever hold your peace kind of thing. So you should probably turn on the flag.

Jonathan Hall:

Yeah. I'm pretty sure we didn't do that at my wedding. My wife might have said something if we had. So

Shay Nehmad:

I just, closed this out in writing ahead of time like a good, Jewish tradition. But, metaphors aside, turn on the flag, see if it works your build, and if it does

Jonathan Hall:

So so just turning on the flag wouldn't be enough. You also have to then pass in a program. So that might require some legwork. I don't know if there's any, ready made caching programs out there. Tailscale has been testing it a lot and using it successfully.

Jonathan Hall:

So I don't know if their work is public. But, yeah.

Shay Nehmad:

I assume, if it's an experimental flag, there's some documentation. We'll dig that up, and we didn't plan to get this much into the weeds. But we'll dig it up and we'll put it in the show notes for y'all. And, I think it's a good open source contribution to, like, test it these things out and even just a comment that says, hey, I tested it out. It it does work.

Shay Nehmad:

It helped me 24%. This and that and this and that were a little bit rough to set up, in terms of the commendation, so maybe let's add some documentation. Just invaluable feedback, honestly.

Jonathan Hall:

Alright. I think that's it for proposals for today. We had a few others in the backlog, but I think we'll save them for later.

Shay Nehmad:

Yeah. We can't we can't talk about about them all. Yeah. But definitely, if someone, wants to open a joke proposal to, ask Yaman in the standard library, that'll make it to the show. But don't do that.

Shay Nehmad:

Don't do it.

Jonathan Hall:

Let's talk about some blog posts.

Shay Nehmad:

For sure. We have some blog posts and some releases to talk about. I dug up 2 that were interesting and good. I think they're both interesting and good. The first one is from Conrad Reich, which are 2 common Go interface misuses.

Shay Nehmad:

And I wanna preface this with a question. Mhmm. You, worked with, devs who came into Go from other languages. Right?

Jonathan Hall:

Oh, yes.

Shay Nehmad:

Did you sometimes have to unlearn or unteach, I guess, some habits of programming that were just ingrained into people? Let's say, I'll I'll pick out a few specific languages. C Sharp, Java, and people who came from Python but did object oriented in Python specifically? Not like, scripters or, data scientists?

Jonathan Hall:

Oh, yeah. I I've I've seen it with Java in particular. I I think that the worst defenses I've seen were people coming from Java and PHP.

Shay Nehmad:

What were the, like

Jonathan Hall:

So with with Java, it was, of course, just abstractions everywhere and, like 15 layers of, like, factories to do something simple. PHP, it was like declaring all of your variables on top of a function, whether you use them or not, and rather than just finding them where they're needed and just sort of, you know, building your application with the sort of the assumption that the entire program runs for each page load. You know, that that sort of mentality that PHP does, leads to a certain style of programming that isn't relevant in most languages, really.

Shay Nehmad:

So I I think this blog post I don't know if that's actually true, but I think this blog post is sort of, in the first paragraph sort of sells its, the the author's frustration where it says, you know, often when coming from languages like Java, interfaces were introduced, you know, people might introduce interfaces into their program because they're trying to be like a good clean code TM object oriented programmers. Right? They wanna do the u m l first and then just click on generate and they'll program their program will work kind of thing. And this blog post, the call to action basically is check if interface if the interface you're using is necessary and if you can write the code without an interface, maybe don't use an interface. And there are 2 specific, quote unquote misuses Conrad had points out.

Shay Nehmad:

The first one is premature abstraction, which I think honestly does make sense. Like, if you have just a single implementation of a thing, the the the TLDR of this, like, part of the blog post is if you have just one of a thing, don't do the interface unless you have to. Mhmm. Because you can just do the one of a thing and you can always add the interface later and ask yourself, will you need multiple implementations of the thing? And will all the implementations share the same method signatures?

Shay Nehmad:

Because you might complicate the signatures a lot and you might never use the the same thing twice. So I found that very compelling, super reasonable. Developers do tend to over engineer. That is a that is a problem and just, you know, stop and check yourself. Am I just doing this because I started typing interface and and without thinking about it, or do I actually expect to use this interface?

Shay Nehmad:

However, I usually do tend to for things like caches, DBs, things like that, write an interface first because my head is, oh, I'm gonna use this in testing. Right? And this is the part of the blog post I I'm not sure I agree with where Conrad says, don't use, mocks for testing where, quote, the second common misuse of interface in Go is creating them solely to facilitate testing, particularly for mocking dependencies like data stores or external services. This is the first time someone has challenged me on this pattern of thinking. So far everybody told me, yeah, Creating an interface and then mocking it is good because your unit test will be fast and and predictable blah blah blah.

Shay Nehmad:

And if you want to have a test that test the real thing, you can still do it if you have an interface, like, you didn't lose anything. So I'm wondering what do you think about this one because I I'm not sure.

Jonathan Hall:

Yeah. I I think there's a lot of nuance missing in this part of the post, and I I agree with some of this sentiment, but I disagree with the ultimate conclusion. I I I'm I think I tend to agree more with you, Shay. So first off, this article doesn't seem to make a distinction. This is a common thing.

Jonathan Hall:

They don't make a distinction between mocks and other types of test stubs, which I think is an important distinction, not so much for the question of interfaces, but for some of the problems I think he's trying to solve. As he says here, it says, for example, using mocks means you test less code. You essentially remove the actual code and are now testing the correctness of the mock implementation. That is a problem, but that's only a problem when doing actual mocks, not other types of stuff, lighter weight stuff like spies and and and fakes. So I don't have any problem.

Jonathan Hall:

In fact, I I really like to use spies in fakes, in just stubs, general stubs in my tests, and that does require using interfaces. I try to avoid mocks in almost all scenarios. There are a few exceptions. But, you know, a mock implementation where, you know, set up this whole scenario when I call this, then I do this and this and this return this and this and this. You know, that that is exactly the problem he's describing here of testing your mock, not your code.

Jonathan Hall:

That's a problem. I think he's throwing the baby out with the bathwater here though, when he says don't use interfaces, because that also precludes using the other types of stubs, which I think are very useful in many cases. And then, his conclusion is, instead of creating interfaces for testing, we should strive to instantiate the concrete type. That's not always the ideal scenario, like you said, with databases or caches or whatever. You know, if it's an in memory cache

Shay Nehmad:

or something. Right? If it's,

Jonathan Hall:

Yeah. Who who wants to spin up my Microsoft SQL Server to run your tests or whatever?

Shay Nehmad:

So who you can stop that at who wants to set up Microsoft SQL Server, but that's

Jonathan Hall:

that's another discussion.

Shay Nehmad:

Yeah. Wait. Wait. Microsoft people, we love you. Microsoft, so go keep up the blog post.

Shay Nehmad:

This is not about you. This is about other other programmers in in Microsoft. You're fine. Anyways, the thing about, like, dummy, fake, sub, spy, mock Mhmm. Let's not get into it here.

Shay Nehmad:

I'm gonna leave a a link to a blog post called mocks aren't stubs from Martin Fowler. Maybe one of my top twenty links I have to put in code reviews for people. There are a few things that I that I that are on my go to, like, they're in my drawer. I should probably bookmark them so I can find them faster at this point. For example, there's this I can't pick up the name right now.

Shay Nehmad:

Maybe Kent Dudes, someone who's doing web mostly in JavaScript stuff, just wrote a really good blog post about don't commit commented out code. Then I see a see a pull request. Someone sends this to me and there's commented out code. And I I can just see that, like, oh, maybe we'll need this later. And then, no, you have it in git, and it will confuse everybody who reads it.

Shay Nehmad:

Like, if you needed to control the system, then it needs to be a a configuration file. If you don't need it, then delete it.

Jonathan Hall:

Exactly.

Shay Nehmad:

So, you know, I I jump to that blog post, copy it over, back, come back to, the pull request interface and and paste that in. Right? The mocks aren't stubs 1 is is top 20. Like, I reach for that all the time. So we'll put that in the show notes as well, and we're leaving a lot of homeworks to a lot of homework to our listeners today.

Shay Nehmad:

We have a lot of links to look

Jonathan Hall:

at. Indeed.

Shay Nehmad:

But but again, the the fact that this blog post invites discussion and is interesting and is about software design and not another here's how to build a HTTP server and go, I build blah blah blah. Super cool. Alright. Shout out. I really really like it.

Shay Nehmad:

It has a lot of good points. We don't have enough design, discussions in Go, I think. I think this is a a good thing. So keep it up, brother. Really good good stuff.

Jonathan Hall:

Let's move on to the lightning round. Music.

Shay Nehmad:

Lightning round. I should do a riff on, you know, the the doors intro? Do do do

Jonathan Hall:

do do. Oh, yeah.

Shay Nehmad:

I could probably pull something out. Well, I'll think about it.

Jonathan Hall:

Alright. It's a recurring it's a recurring segment, so we could you don't have to do this week. You could do it later and we could Yeah. Future. Alright.

Jonathan Hall:

Well, hiding around the 2 things I wanted to pull out, of the interweb database, whatever. Reddit lately is doing FAQs for commonly asked questions. This one popped up on the radar. What are the best GUI solutions for Go? And we've talked about a number of these in the past.

Jonathan Hall:

Right at the top is, fine from front of the show, Andy Williams, who posted on, the FAQ item there. Some other good ones. Wales is another it's sort of like Electron, but written in Go. There's a few others on there and a new one that it might be on the list. I didn't find it yet, but it came onto my radar otherwise is, MiQt.

Jonathan Hall:

MIT license QT bindings for Go or just released about a month ago. I've seen this come up a couple places. So if you're interested in writing qt applications for Go, that's what I check out.

Shay Nehmad:

I'm wondering what's the use case for using Go. Like, you have to have a fully functional c plus plus pipeline cause these are just bindings. Yeah. So I'm wondering if that's not forcing the issue a little bit. But maybe if you wanna take an existing program and then just slap in a gooey on top of it.

Shay Nehmad:

Right?

Jonathan Hall:

Oh, sure.

Shay Nehmad:

That would make sense. More libraries is more gooder. More Turkish is better. Talking about all these, you know, GUI libraries, let's talk about back end instead. I've been putting my my head to the grind stone and nose to the grind stone and really trying to work on the migrations problem.

Shay Nehmad:

That's a really difficult one. I've even bought some books about it trying to figure out how to make migrations easier. Out of nowhere, I see pg roll. Zero downtime migration for Postgres just had a new release, supporting, pg 17 and improved their performance by 80%. So this is a very specific problem but if you are worried about migrations in wherever you work on whatever app you're working on and you probably should be then take a look at pg roll.

Shay Nehmad:

I I haven't tried it yet but it looks pretty good. Zero downtime reversible schema migrations for Postgres. I mean, what's not to like?

Jonathan Hall:

Interesting. Well, I can

Shay Nehmad:

tell you

Jonathan Hall:

one thing I don't like. What? I don't like the reversible part.

Shay Nehmad:

What do you mean?

Jonathan Hall:

I think that's a mistake.

Shay Nehmad:

I think we're gonna have to break the rules of the lighting around and talk about this.

Jonathan Hall:

Which is why I've written my own, migration library that specifically has reversibility as a nongold. So I'll put that in the lighting around too. It's called burrow because how do gophers migrate? They burrow.

Shay Nehmad:

Oh, that's funny. That's a good one. That's a good one. I'll give you that. But wait.

Shay Nehmad:

Why wouldn't you want reverse to reverse the migration? Let's say I I released I rolled out a a version. I have blue green deployment. Right? Blue is the active one.

Shay Nehmad:

I roll out the new version to green and the migration has a bug. Right? Why wouldn't I wanna roll back to the previous version of the code and roll back the migration at the same time?

Jonathan Hall:

Because many rollbacks are not reversible in the first place and, putting making it part of your migration library gives people the false security that they are.

Shay Nehmad:

Oh, but but some are. Right? I add the column. I can

Jonathan Hall:

But those are easy to reverse anyway without, support in your library. That's my opinion. Which really has nothing to do with Go, and I I know a lot of people are gonna disagree with me. So maybe we'll save that for, Slack channel.

Shay Nehmad:

I will say that you probably don't disagree with the zero downtime because

Jonathan Hall:

I like to do that.

Shay Nehmad:

To do yeah.

Jonathan Hall:

Yeah. I like that.

Shay Nehmad:

Do you have, government websites that don't, that that have, like, scheduled 8 hour down times?

Jonathan Hall:

I had that, was it it was immigration website maybe? I can't remember. It was so annoying. Like, you you can't use this website right now. No.

Jonathan Hall:

It wasn't even downtime. It was just like we're only open during business hours. Like, a website is only open during business hours. What what is that?

Shay Nehmad:

So in Israel, you also have, some websites shut down for, like, Shabbat and and holidays. Okay. So they'll be open not during business hours during the week, but, you know, we do wouldn't want our servers to be, I don't know, not kosher so they're not working Friday nights. Awesome. I'm down I'm down with, everybody's religious decisions.

Shay Nehmad:

That's just funny to me. Yeah. Anyway, I really like this, library. There's a blog post. There's visual documentation which is super useful.

Shay Nehmad:

We're talking about databases, migrations, downtimes, schemas, things like that. Very good stuff. They just had a new release, last week. Really, you know, configuration of batch sizes, backfill performance up by 80%. And again, support for post v o seventeen, which I don't know, when do you think, post v o seventeen was released?

Jonathan Hall:

2 weeks ago.

Shay Nehmad:

Super fast. Yeah. Yeah. Yeah. It was released, September 26th.

Shay Nehmad:

Less than a month. Yeah. Really, really good turnaround times, guys. Super cool stuff. That does the show.

Shay Nehmad:

Stick around for the ad break, and then we're gonna yap a little bit more about an interesting Go topic I found this week, and, we wanna dive into a little bit deeper. See you then. Welcome to the ad break. This is a good chance to, take a break, refresh your coffee, refill your cups. What's that?

Shay Nehmad:

You don't have a cup next to you? Oh, I have a solution for that. I want you to go to store.capago.dev or just go to, cupago.dev where you can find all the links anyway. Like we mentioned at the top of the show. Oh, I'm just having a brain fart.

Shay Nehmad:

We didn't.

Jonathan Hall:

No. We didn't. Like we should have mentioned at the top of the show.

Shay Nehmad:

It's fine. We didn't say it at the top of the show, but this show is supported by you. This is a pretty expensive hobby mostly paying for editing, hosting fees in our time. But we do have, supporters, our beautiful Patreon members. Thank you everyone.

Shay Nehmad:

We have a new member. Thank you a lot, Steven Clark. This is like a superhero name, Steven Clark. Thanks a lot for joining as a cup of gofer. We really appreciate it.

Shay Nehmad:

If you can kick us $8 a month, we would really appreciate it. Just, very much validates the value of the show but it's also fine if you don't. Like, if you're just listening and you're here, we really appreciate you. Other than that, just the normal stuff. Feel if you're a normal time listener, now you can do the 30 second skip button on Spotify.

Shay Nehmad:

You can find us at capago.dev. We're on the go for Slack at hashtagcapago.dev kebabcasewithhyphens or you can email us at news atcapago.dev. That is news atcapago.dev. Other than financially supporting the show via Patreon, you can buy some swag on the store or you can share the show with other people. We're we do not pay to advertise and we don't do a ton of promotion, social media, things like that.

Shay Nehmad:

So leaving a review on Spotify, Apple Podcasts, wherever you listen to your podcast, sharing the show with a friend or a colleague or a co student is a really good way to to put us out there. The episodes have been doing really, really well lately. We had a few strong interviews, like, in a row. People seem pretty happy with the with the show. So, let's keep it up.

Shay Nehmad:

And next up, we have an interview with just us yapping. We found a topic that we wanna dive into. So something a little bit different this week.

Jonathan Hall:

Alright. So, Shai, we're gonna be talking about, a tool, but I think more importantly, a topic. Right? So that this there's this tool called Vale, which I think sort of triggered, the topic in your mind, technical writing, and some things like that. This is your topic, but I think you're gonna mostly be asking for for some of my feedback.

Jonathan Hall:

So why don't you kick us off? Let us know, yeah, where where where your thoughts on this topic?

Shay Nehmad:

So so here's where I am. Right? Here here's where I'm at. Right? I joined Orca about, like, a year ago.

Shay Nehmad:

Right? And one of the things I'm doing there, not in any official capacity, this is just how I do my job. It's right at daily blog. This is something I've been doing for many years now. I actually talked about this in the small bites bite sized, but I don't remember the name.

Shay Nehmad:

The Josh Bleecker Snyder podcast. Mhmm. I just it helps me focus and then if I have some trick, oh, here's how you debug a CI pipeline using teammate or here's a cool one liner that helps me connect to SSO in the morning, just I don't have to worry about where do I put it to share it. This is something I'm also doing in my personal life using log seek. But when you're in a company setting when and you publish it every single day, it has a lot more impact.

Shay Nehmad:

I'm I'm way into writing stuff down even if it sucks. So I started doing that when I was there a year ago and now ever like since then my team I I opened the team and then it grew and grew a little bit more, and also it has, like, time behind it at this point and we we have some new things that we have built like, I don't know, integration with Pyroscope. And we have some old stuff that we inherited, like the deployment process. That's been existing since day 1 and and now we're in charge of it. Right?

Shay Nehmad:

Mhmm. And you know I didn't write that trick because it's in Python. So obviously, we're at a point where we have the competition strewn all over the place. Some of it, read me files, some of it confluence, actually a lot is in confluence. A lot of it is actually Slack control f based kind of thing.

Shay Nehmad:

Like, there's a lot of technical content in our Slack, more than you would expect, I think, more than I ever have. And people definitely think about Slack as a knowledge base. Some of it in swim, which I don't know if you've heard about, but we'll definitely talk about it because it's it's super relevant. Mhmm. And my my thoughts for my team were, like, I don't want my, devs to worry about where to, put stuff.

Shay Nehmad:

We have quite a lot of operations, like a lot of on call. Right? We're in charge of processes that require manual intervention and fixing, at least for now. And I think the best way to deal with that is just write the documentation down. Right?

Shay Nehmad:

Because that way when the next on call comes on next week and they have the same bug, they can control f it and quickly find the what happened last time, etcetera etcetera. So one of my developers, had a really good idea. Let's open a repository, just shove some markdown files there and then we can use some tools we already have, like swim, to to manage that. And then I went on a absolutely if for no reason no reason at all, I obsessed about that repository for, like, 5 hours and dug up Vale. I don't know if you ever had that.

Shay Nehmad:

Like like a a manic night of working on something that's absolutely not your top priority just because you're hyper I think the word is hyperfixating but I don't know if that's like a legitimate medical term so I don't wanna misuse it. But it definitely felt like hyperfixating on this one specific repo just because I really really really wanted to make it good. Now, the place where I'm at is I wanna make the perfect team repository for documentation. With all the integration and all the tooling and all the whatever. For technical documentation, not for like for things like ADRs, for things like runbooks, for and not like project status updates and not for, like, meeting summaries.

Shay Nehmad:

You know what I mean? Uh-huh. Just for for quote unquote hardcore technical documentation. That's where I'm at right now. The the the place where it ties into Go is Vail, this, prose project that's a 100% written in Go and I found super interesting.

Shay Nehmad:

Mhmm. So my first question is, what is the best technical documentation you used? You know, how did it look like?

Jonathan Hall:

How did it look like?

Shay Nehmad:

Internal. Internal. I'm not talking about, like, the Go docs or or or a company that has to sell you a thing and then, of course, the documentation has to be good. I got, like, internal team docs.

Jonathan Hall:

So my I'm not sure if this is quite the answer to the question, but, like, my my sort of go to is a Wiki of some sort. The platform doesn't matter as long as it's not Confluence Or or MediaWiki for that matter. That's also terrible.

Shay Nehmad:

Not not sponsored by, Confluence, but we use Trello. And ever since Atlassian bought it, we hate it.

Jonathan Hall:

So I I think I think Wikis are great because it's important for it to be easy to update. A repo can be the same, of course, like, GitHub Wiki pages are a repo in the back end without all the CI pipeline stand against. Yeah. I mean, I probably usually use GitHub Wiki or GitLab Wiki, whatever tool I'm using, you know, whatever built in Wiki they have. And then I think the more important thing isn't so much the technology it's using, but sort of the practices around around the how it's updated, who has permission to update it, what what should go in it, all that sort of

Shay Nehmad:

stuff. So I'm thinking my thought process is this. The main problem with documentation well, I don't know if the main problem. I don't wanna be hyperbolic. One of the problems with documentation is getting people to do it.

Jonathan Hall:

Yeah. Right?

Shay Nehmad:

It's not like people are on their feet, just let me document, please. And people are like, no, do something else. Usually, you have to convince people to do documentation. And I think it's over a sort of a habits thing where if they have really, really good tooling and a really, really awesome process and a good feedback loop about documentation, they might document more, which is what I'm I'm one of the things I'm trying to create. Like, if you write your thing in a wiki, do you know how many people read it in, for example, GitHub wiki?

Shay Nehmad:

Do you have, like, x people viewed this? Because Confluence does have that. Yeah. And that does hack my brain. When I see a blog post that I wrote and, like, 50 people in Orca read it, that's huge for me.

Shay Nehmad:

This is not such a big company. That's, like, 10%. K. So I

Jonathan Hall:

I guess I've never, aside from my personal slash, you know, my personal business blogging, I've never really cared about how many people read my thing. But I I I suppose I could see that being valuable.

Shay Nehmad:

No. What I'm what I'm asking is did was the problem of not is the wiki a good platform, but did you ever encounter a team that were pretty good at the comment at documenting? I'm not even saying excellent because that's really, I think, rare. But a team that were just really good and the reason I'm saying a team and not a person is because there are a lot of people who like to write and and tend to document. And I'm talking about a culture around it and not just a specific person who's, like, just documenting all the things.

Shay Nehmad:

And then if it's a project, it's a feature written by someone else, there's nothing.

Jonathan Hall:

I I've worked with sub teams. Like I worked on the infrastructure team at one company I was at a startup I was at a few years ago, where it was a small team like 3 of us, we were pretty good at documenting things. A big part of that though was shifting the documentation to be auto generated as much as possible from things, from from, well, you know, the equivalent of an open API spec or something like that.

Shay Nehmad:

Mhmm.

Jonathan Hall:

We weren't actually using open API there, but, you know, you you get the idea. Right?

Shay Nehmad:

Yeah. Yeah. Like, if you can document it in things that are actually

Jonathan Hall:

code, that's better. Right.

Shay Nehmad:

Alright. So here's what I'm thinking. Let let me pitch you. You want the writing process to be good? That's where Vale comes in.

Shay Nehmad:

Let's talk about Vale for a sec. I want the the writing process has to be good, so it has to be, text files that you can edit on your favorite editor or in the web. Not Confluence, not Notion, not Evernote, not Logseq. All of this all of them text editing platforms. One of them I like.

Shay Nehmad:

And you know what? Actually, Evernote

Jonathan Hall:

It's not Notion, is it?

Shay Nehmad:

No. It's not. It's slow. Okay. Good.

Jonathan Hall:

Because I hate that one too.

Shay Nehmad:

It's slow. It's slow. It's Logseq. I really like Logseq. Okay.

Shay Nehmad:

But, I use Logseq personally where I don't have to worry about collaborating with anyone. Just shy from 6 months ago. Right? So Yeah. It it doesn't have really collaboration features.

Shay Nehmad:

Awesome for me. That's also super privacy aware. We're not talking about log sec right now. Don't distract me. So writing has to be good.

Shay Nehmad:

It has to be simple markdown files. Right? There's this guy on YouTube called no boilerplate. He's a Rust developer, but whatever. Has a whole, like, 15 minute video about how you can run a whole company just on markdown, and text files.

Shay Nehmad:

And ditch all these platforms, blah blah blah. Use Kitha projects for your Jira. Use, just text files for your documentation, and you wouldn't believe how much, blah blah you're gonna save. I actually agree.

Jonathan Hall:

I do too.

Shay Nehmad:

So writing has to be nice. Content has to be good. Again, that's where Vale could come in. Vale is a open source Go project written by a sole developer, which is really cool. It's also good to mention it on the show because it had a new release, recently.

Jonathan Hall:

Yeah. Just 3 days ago. 3.8 came out.

Shay Nehmad:

Oh, damn. So that's even newer than the thing I, I posted on our backlog because it's, it's been sitting there for a while. So what is Vale? Do you use Grammarly, for example?

Jonathan Hall:

I tried it once and I absolutely hated it.

Shay Nehmad:

Oh, that's interesting. Why?

Jonathan Hall:

Yeah. Because it was wrong most of the time.

Shay Nehmad:

No. Okay. You don't like the Oxford comma?

Jonathan Hall:

No. I love the Oxford comma. No. To be fair, it was a few years ago when I tried it, but it was telling me to correct things that were not wrong. Like, I'm better at grammar than grammarly as early as I was at the time.

Jonathan Hall:

And it was also slow and just cumbersome. So, yeah, it was I didn't

Shay Nehmad:

So I'm still a user because English is not my first language and it does catch me on some things that I miss sometimes and that's totally fair. But it it is better at grammar than I am. I think that sentence was wrong in gram it was, like, had wrong grammars. I think it's not a huge endorsement. It's it's a lot faster than it used to be.

Jonathan Hall:

I'm gooder at grammar than grammar language.

Shay Nehmad:

Yeah. Totally. It's a lot faster than it used to be. It has AI features. I don't know if that's a turn on and a turn off for you, but it is super super cumbersome.

Shay Nehmad:

And and Filippo, you can edit that out because I cannot, stop myself. I would, like, go into a text field in a form, you know, do trying to do, like, programming somewhere.

Jonathan Hall:

Uh-huh.

Shay Nehmad:

And if it's on the web, it's gonna put the huge Grammarly thing all over and I can't read the thing.

Jonathan Hall:

Yeah.

Shay Nehmad:

Ugh. But anyway, I don't think it's relevant for markdown files. Right? Because you have to edit it somewhere where Grammarly works. You're not gonna turn on Grammarly in your v s code etcetera etcetera.

Shay Nehmad:

Vale, for me does what Grammarly should have done which is let me write, stay out of my way, give me levels of, like, correction and not try to sell me on premium all the time because I never paid for Grammarly. Run super fast, written obviously in Go which is why we're talking about it here. And it's sort of a linter for for English text, for prose. Right? So it knows how to read like markdown and and it has actually parsers for a lot of languages.

Shay Nehmad:

The release I wanted to mention, 3.7. Something, brought a Julia parser. So you can turn Vail on on Julia code for like jl files. It's pretty interesting. I never used Julia but cool.

Jonathan Hall:

I haven't either. Yeah.

Shay Nehmad:

But if you have markdown files and you have the linter on it, it has very good built in rule sets like the Google style, style set and some NLP complexity things. Things that just make your writing better. So it works like a linter, it has a really good built in rules, The Google style, this is how headers should look, blah blah blah, which I think is really important for documentation, like uniformity. And also some NLP things, which I I understand slightly less, but I do think they would make your writing better, like some complexity, calculations that count the number of syllables in a sentence and then how long does, like, the average number of syllables per word and the length of the sentence and then puts it on, like, x y and if you're going too far then it tells you, hey, your sentence are too complex. Especially working with with teams whose, first language is not English, I think this brings a ton of value.

Shay Nehmad:

Sure. But I'm I'm wondering if if you as a developer, if you were writing documentation and someone was like, hey, your blah blah blah complexity score is 8.5 instead of 8. Would you, like, hate them or you will you appreciate the the comment?

Jonathan Hall:

If a person told me that, I'd I'd probably tell him to buzz off. If a tool told me that, I might care. So I I I do care about that sort of thing when I'm blogging because I want to I want my my blog post to be as accessible as possible. You know, I I want I want a high school student to be able to read my blog post as well as, you know, a compiler author, you know. So I want to write at the lower lower level, most of the time.

Jonathan Hall:

What I'm I think the high

Shay Nehmad:

schooler has better reading comprehension skills. Right? Because they he's saying more English than assembler.

Jonathan Hall:

But when I'm writing internal documentation, I don't care nearly as much about that. I mean, I might care some, but I don't care nearly as much because I'm not I'm running for a very, very limited audience. I know my audience.

Shay Nehmad:

Okay. So when you're writing internal documentation, you might say like, you might be more prone to writing worse English?

Jonathan Hall:

Or or not not necessarily worse, but but more technical English. So, like, if it tells me this is, you've written at a, say, a 10th grade level versus a 6th grade level, I probably prefer the 6th grade level for a public blog post. And for internal stuff, like, I I I'm gonna assume that my colleagues can read it at 10th grade level. I don't really care.

Shay Nehmad:

So here's here's a curve ball. One of the rule sets that the way Vail works is that it's not just a linter with built in rules, it's a linter then you have to install sort of extension rule. I didn't understand a 100% why it's built that way, but whatever

Jonathan Hall:

Sure.

Shay Nehmad:

Works well. So you need to pick and choose your your style guides, Right? And your sort of rule sets, whatever. Right. And one of them is called Alex.

Shay Nehmad:

And Alex will inform you that you have used the word simply, which may be considered condescending.

Jonathan Hall:

Okay.

Shay Nehmad:

Yes or no? Is that is this good? Or would you tell it to, you know, minus minus no verify?

Jonathan Hall:

If I use the word simply, I probably mean it. I don't use it very often. I can see why it would be condescending. My bigger concern is that it's superfluous. Like simply type this at the bash script, like just leave the word simply out and the sentence doesn't change meaning at all.

Jonathan Hall:

So I would be more concerned about just being overly verbose than it being condescending. Although, I could certainly see uses of it being condescending in LinkedIn, for example.

Shay Nehmad:

I mean, would you say it's possible that you read a a technical documentation? I don't know why I'm, like, lawyering the all these questions up, where someone used, really insensitive or ableist language just because they were really angry. Right? This process this CI process is is idiotic. Therefore, blah blah blah.

Jonathan Hall:

I I do that in my, in my, Git commit comment sometimes. Like, remove stupid, redundancy or something like that. Right?

Shay Nehmad:

So I think Git commits are are a good place where all developers sort of agree they can vent, especially not in the topic line, but in the paragraph frame, which no one will ever read unless you introduce the bug. Which is why, by the way, the side note, I think it's very unfortunate that, some people are using AI to summarize their commits and write their commit message.

Jonathan Hall:

This is

Shay Nehmad:

like the only place you have left for creativity, man. Like, but anyway, you know, there's there's a a whole list here of, you know, you shouldn't use moron because that's ableist.

Jonathan Hall:

Okay.

Shay Nehmad:

And you probably don't wanna use mankind because that's gendered if you can use humankind or man hour instead of hour of work. There's some racist things here, like, don't use Eskimo. I I didn't even didn't even know that's a bad word, so good for me. But, apparently, you should use, Inuit. Although, I don't know how many of them are really offensive and how many of them are, like, people being a little bit too sensitive.

Shay Nehmad:

Sure. But if I'm writing the commendation, and, you know, I see some things here that I wouldn't like to see in the commendation. For example, shyster or shlomo

Jonathan Hall:

instead of Okay.

Shay Nehmad:

But saying But

Jonathan Hall:

Jewish person. So so on the one hand, I can agree that a lot of those things shouldn't be in documentation. On the other hand, I've never seen them in documentation. So why do we need to go to the effort of implementing a rule or or a tool to take them out?

Shay Nehmad:

You've never seen profanity or gendered or condescending, like, someone saying, of course or easily or simply or obviously or everybody knows.

Jonathan Hall:

Okay. So I've seen I've seen some of those things, but I don't think that I don't think it's a problem big enough. I I haven't seen a problem big enough to warrant a tool. I guess somebody says obviously in a documentation. That's, again, an example of superfluous language.

Jonathan Hall:

Just take it out because it's just it's slowing me down. That's my annoying. It's not that it's condescending, it's that it's it's getting in the way of the information I need. Now, if somebody's saying Eskimo and documentation for one thing, what are you documenting and why am I on your team?

Shay Nehmad:

How did we get here?

Jonathan Hall:

But yeah, Okay, so if if a team is having sexist or racist documentation, I I feel like this. I mean, maybe a tool is one part of the solution, but like just talk to people doing it in in in. Maybe that's a difficult training subjects. In some cases, I don't know. And maybe a tool can help, but it's it's not it's not been an issue that I'm aware of.

Jonathan Hall:

Maybe I'm just not aware of it because I'm a a white CIS guy. I don't know, but it hasn't seemed to be an issue. It's never come up in a retrospective or an HR meeting or anything like that.

Shay Nehmad:

Mhmm.

Jonathan Hall:

So So it doesn't feel if you know, it feels like it's a problem. It's a solution looking for a problem in my in my context.

Shay Nehmad:

This is just the thing that caught my eye is that when I turned on veil, it didn't find anyone writing, like, Jewish slurs in the documentation or any other slurs for for that matter. That that

Jonathan Hall:

would be unusual where you live, I would imagine. No.

Shay Nehmad:

It might be more usual than you'd expect. But, actually, we have a few different, like, religions and things on my team.

Jonathan Hall:

It's pretty cool.

Shay Nehmad:

But the the thing I'm I'm I was surprised by is every place where it says, hey, simply might be condescending. When I actually read the line of the commutation, I saw, hey, either it's telling me something, like, silly that I already know and I need to delete. Like you said, it's a performance or it was the way, like, it's obvious how to do it. It was a way of the developer to sort of, you know, skip over a thing that they actually needed to explain because I didn't know how to do. Right?

Shay Nehmad:

We documented something super cool tool that we could talk about forever, also written in Go by the way, called multi gitr. You run a thing and it runs it on all your GitHub repos. Super useful if you're working in a GitHub org. Right? And I wanted to have, like, a document for for people on the team because we do that sort of stuff all the time as the engineering enablement team go over every single repo and do a thing.

Shay Nehmad:

And then it was obviously you need the GitHub token. It's like, wait a minute, that's not obvious. Which one? Is it my user? Do we use the service account token?

Shay Nehmad:

Like, you just wrote obviously instead of explaining what I need to do and this is condescending because I don't know what I need to do. So I think this sort of sparked my thought process of, like, this is not about this is a linter. That's not about, like, oh, markdown lines should have one new line between the title and the blah blah blah. But it was actually about the content Okay. Which I found very interesting.

Shay Nehmad:

It's a great project. Honestly, super props to the guy who built it, sole developer with a lot of sponsors and supporters. If your company uses it or you think about using it, you know, Algolia, Mongo, Fastly, Reductly, Commerce Tools, g a m b h, like, some and it's used by Microsoft and Google and Melee search and Datadog and Linode and Docker and GitLab, like, Grafana, OpenSearch, Cloudflare, all over the all over the map.

Jonathan Hall:

Basically, everybody and their dog is using it, so you should too.

Shay Nehmad:

Yeah. Yeah. I can't believe I I haven't heard of it. So that's about making the content, good. Right?

Shay Nehmad:

Mhmm. Now you need to worry about making it maintainable. Mhmm. I don't know about you, but my first thought when I open a Confluence doc, the first thing I look at is, like, I scan the thing and see if it's relevant and then I scroll back up and I look at the update date. Right?

Shay Nehmad:

Mhmm. And last updated by. And if the update date is recent and the last updated by is still working here, then I consider that document relevant. And if it's 2 years ago and the person is, like, you know, in, Atlassian systems fired people are, like, gray Yeah. Their icon is, like, gray, and it says, like, in prints deactivated, I think of it as

Jonathan Hall:

It's suspect information. Right? Yeah.

Shay Nehmad:

How do you keep did you in in the past in these, like, really good teams keep documentation in line and, like, correct?

Jonathan Hall:

So on on the team I mentioned at the beginning, of the the conversation, a lot of the documentation was sort of automatically kept updated just by by systems. You know, whenever something whenever a Yamo file change, the documentation was generated at the same time. One of the practices I really like to do is, especially for like onboarding documentation, is like, tell the person who's joining the team, your task today is to read the documentation and do the things and submit a pull request at the end to update anything that's wrong. So that's one way to help keep things updated. And then that helps to to start build that culture of just update documentation all the time.

Jonathan Hall:

Whenever you discover something is out of date or whatever, update it.

Shay Nehmad:

So I agree that doing the culture thing and telling people to, do the competition all the time, especially in onboarding where you have a lot of eyes on you sort of thing, and and you don't have tasks, so you're just onboarding so you can take the time, that's a good place to instill that, but I I also am a very big proponent of swim, which I mentioned a few times. Hashtag not sponsored. They they don't know I'm gonna talk about them but I I have been working with them for for a a lot of years now, since 2019, I wanna say. It's a very simple concept. You write a document in their either in your editor, they have ID extensions for everything and it's saved into Git as markdown files.

Shay Nehmad:

But wherever you reference code, it it like points to the file. It's a pointer to the file that says, oh, the the snippet of code you introduced is from this file. And then if the code changes, CI is gonna tell you, hey, please make sure that this document is so fresh. Right? Because the snippet changed.

Shay Nehmad:

And and then when you do a how to guide and the file you mentioned is deleted, you know what I mean? It's gonna be, oh, wait. This guide is not right anymore because we changed that. It is cool. I'm a big proponent of that.

Shay Nehmad:

It needs again, it's a culture thing, right, because it's very easy to turn off the CI that checks that and turn off the pre commit verification that checks that and just let your documentation rot. And it's even easier to not write any documentation at all. But it does a lot of things right. It also has a lot of AI features right now that I think are actually useful which is like I wrote a pull request then you have a button that says create documents from pull request. Like, if you did a repetitive task, oh, deploy a new region blah blah blah, something like that in in infrastructure as code.

Shay Nehmad:

The guide on how to do that normally is, oh, look at that example PR and do the same thing. But if you spend a little bit of time writing the documentation about it based off of the PR and you have AI, like, doing all the boring parts for you and you could just add the references that are extra relevant, I don't know. I found that feature really useful.

Jonathan Hall:

Cool.

Shay Nehmad:

So finally, we have we have writing. Right? We said markdown. We have, content to good, which is veil. We have main maintenance, which is swim.

Shay Nehmad:

And for every one of these, I assume, by the way, there's a drop in replacement. Like, if you're not into markdown, that if you're into RSC, or if you're into wiki files and you want to do it like that, like, that's fine. Hey, my CV is in my CV is in LaTeX.

Jonathan Hall:

I love LaTeX, but not for this sort of documentation.

Shay Nehmad:

No. For sure. It's actually really good for CV's because Yeah. It it it really makes me wanna keep my current job because I don't wanna update that thing. Anyways, so, you know, you can replace it.

Shay Nehmad:

And Vail, I'm I'm sure you can do Grammarly, like, you can buy Grammarly Pro and probably the extension for confluence and then have that work. Right? Or any there are even open source Grammarly alternatives by the way. I haven't tried them because I just use Grammarly but whatever.

Jonathan Hall:

Mhmm. Yep.

Shay Nehmad:

For keeping documentation in sync, I'm not sure there's anything out there like swim just because I've been using swim so I haven't been looking but I assume there are similar things. Last piece of the puzzle for me is searchability and and like findability and discoverability and these sorts of things, right? My developers live in Slack and GitHub maybe, right? And their editors which are open on a specific repository, I don't know which one. That's it.

Shay Nehmad:

Like honestly, I don't love them opening Confluence, Right? For meetings, that's great. Like if we're doing brainstorming or retro and we need to all put a whiteboard together blah blah blah and document it. That's fine. And log task, we do we use Jira all over the company so no question.

Shay Nehmad:

We'll use Jira as well. Fine. But other than that, that's not where they live but I do want them to find the documentation. And this is where my my brain is sort of stopped right now about the the the discoverability. Like, I wanna publish every single change to every single document to Slack and Confluence and TechDocs on Backstage and just wherever people might to do control f, I want them to find the documentation.

Shay Nehmad:

Right?

Jonathan Hall:

So that's one place where Confluence is good, in my experience. Searching for documentation in Confluence is much better than on GitHub. Wiki GitHub search is terrible.

Shay Nehmad:

So what what I'm imagining is the perfect repo is whenever, documentation gets merged, it gets published all over with backlinks to the source. Like, you don't read this thing on Confluence, you find it on Confluence and you may choose to read it Mhmm. But there's a big, like, warning slapped automatically on top that says, hey, this was originally posted on and is only maintained on like getup.com/yourcompany/vesteemedashdocs. If you have this template that sort of does this and does this super well for confluence and and also Slack which is where I'm even more confused because do you just have automated documentation publishing channel where you just push all the documents all the time? Like, what do you do to make it findable with a with a big fat link on top?

Shay Nehmad:

Hey. Here's the actual document that you're looking for.

Jonathan Hall:

I don't I don't know the answer to that. I I I have never found I I have not yet seen a good discoverability interface to documentation. Part of that's because, like you mentioned, is often scattered across multiple instances that you have things in Google Docs. You have things in. Maybe notion and confluence and GitHub and Slack and email or whatever.

Jonathan Hall:

Yeah, the best I've ever come up with is is have have a well defined entry point for everything, whatever it is. And then if it has to link to other places, including Slack conversations or or whatever, you know, that's okay. It's better if everything's in the same place, but when it can't be at least reference it there With a reasonable on a subscription that a search is likely to find it.

Shay Nehmad:

So what I'm thinking is it it'll be a lot easier for me to put just publish my documentation to Slack and Confluence in, like, not very visible places, just searchable places. Mhmm. Right? Just a dump of here's this text and you can find it if you control f for it, and then here's the link to the actual documentation.

Jonathan Hall:

I would hate using Slack for that, but I I can see why it would be useful.

Shay Nehmad:

Well, it's just when there's an error, people tend to copy the error and then control f it in Slack because maybe someone we have a bit we have a lot of, like, FAQ technical channels. Sure. Where developers are just like, hey, here's a bug I'm I'm experiencing. Anyone has any idea?

Jonathan Hall:

Mhmm.

Shay Nehmad:

And I one very specific example that's very searchable is iTerm introduced an update. We use Max at Orca. Mhmm. Introduced an update that changed the default date to your location, like geographical location. Mhmm.

Shay Nehmad:

So your date locale, not time zone. Locale turn to Hebrew. Even if you're even not a Hebrew speaker, you're just in Tel Aviv. And suddenly, all our shell commands that were based on typing the command date, right, and parsing the date to check, I don't know, how long do you want your development environment to be alive for? So it's like, resume my development environment for 5 hours, enter.

Shay Nehmad:

And it's like, I don't know what you want because there's it says, Yom Shani Hill. Well well, like, what the hell does this mean? Monday, by the way.

Jonathan Hall:

So weird.

Shay Nehmad:

Yeah. Yeah. Yeah. So this this is sort of thing where people just go to Slack and, like, anyone else experiencing date issues Sure. Then they just find the thread immediately and have the answer immediately.

Shay Nehmad:

I mean, it works. I don't know if I like it, but it works. And people live in Slack in my company right now. So why why fight it and tell them, hey, if you want to learn about my team's documentation, go there, instead of just shoving it to Slack and and making it searchable? What what am I losing?

Jonathan Hall:

Yeah. I can see the I can see the argument.

Shay Nehmad:

So so Vale really sparked this sort of, incessant thread in my mind Yeah. That I I believe I I can build the perfect documentation template repository that every team can take. Not not just in my company. All over, you just need to, you know, add the relevant instead of Confluence, oh, we use Wiki or instead of Confluence, we use I don't know. Whatever.

Shay Nehmad:

Alright. I'm wondering if if that's possible or if that's a fool's errand because So every team is I

Jonathan Hall:

would take issue with the idea of perfect because I think every context is gonna have different is is gonna want different trade offs. So What do you mean? Let let let's imagine you're in a in a situation that has a lot of privacy, concerns, and you don't want error messages being shared on Slack that might contain sensitive information, for example.

Shay Nehmad:

Well, you go to william.dev, and he tells you how to not include sensitive information. Well, I

Jonathan Hall:

mean, that that's that's great, but people are gonna do it. Right? So so maybe you implement a policy that Slack conversations are only searchable for a week or or they're deleted completely after a week or something like that. So then then that that, you know, don't have anything to Slack isn't gonna work. I I I just made that up.

Jonathan Hall:

You know, I don't I don't know if that's actually described to anybody, but I do think that there are gonna be different contexts where different trade offs are required.

Shay Nehmad:

So perfect is not referring to the tool here. Perfect is referring to the bones. Like, you need to write the documentation, you need to maintain it, you need to make it good, and you need to publish it.

Jonathan Hall:

Where your internal documentation is also public documentation?

Shay Nehmad:

They have runbooks. That's where I took the, inspiration from.

Jonathan Hall:

But they're not dumping them to Slack is my point.

Shay Nehmad:

Well, that's because they're searchable on Google. Right? I assume that when GitLab well, first of all, I assume that they do have an internal

Jonathan Hall:

They probably do. But but they also make a point of discussing their issues on the public facing issues, the get lab issue tracker, right? So that they're searchable by the public and indexable by Google and so on and so forth. So I'm not saying you're wrong. I'm saying that I think there are contexts where some trade offs are going to be different.

Jonathan Hall:

So I don't think, yeah, I I think what's perfect in one context is gonna be imperfect in another. So I don't think you're gonna ever find and not just in this domain, but I don't think ever gonna find the perfect tool, all situations, which is close to what you what you step said.

Shay Nehmad:

I agree. Since I obsessed about it for, like, one evening, and after talking to you for, like, the last whatever minutes it's been Yeah. I'm, like, oh my god. Let's get off this call. I wanna start building this template repo.

Shay Nehmad:

Alright. I think it's it might be inevitable. I think I'm just gonna build this thing. It's just glue. Like, it's just these sort of glue tasks that I I don't know if you found yourself, in this position where you have you're the glue guy.

Shay Nehmad:

You're not like the product manager

Jonathan Hall:

I am the glue guy.

Shay Nehmad:

Or the lead dev.

Jonathan Hall:

Yeah.

Shay Nehmad:

You know what I mean? Like, these sorts of tasks that are I don't know if they're they're always not critical, they're always not urgent, and they're very important.

Jonathan Hall:

What it what it sounds like I'm hearing you say is that you're about to go build a framework.

Shay Nehmad:

Yeah. Yeah. I am. You know what? I am.

Shay Nehmad:

And I I'm not afraid to say it. But it's just a template, Greppo. Just one more you know that meme just one more tool, bro. One more tool. It's gonna be One more tool.

Shay Nehmad:

Just one more tool, bro. Promise. Promise is the last tool. The thing that's excites me about this is the fact that I really want this to work at work. Like, I really, really want this to work for my team.

Shay Nehmad:

We're a new team taking on old software, And if we crack documentation, I I believe it's gonna be transformative for, like, and our entire, developer experience and and productivity.

Jonathan Hall:

Awesome.

Shay Nehmad:

It's it's wonderful.

Jonathan Hall:

Well, I I am looking forward to hearing, updates from you as this project goes forward.

Shay Nehmad:

Get it done. Yeah. Cool. We don't have a interviewer to ask, when I started learning Go. But I started learning Go in, 2

Jonathan Hall:

When did you start to learn English? We could do that one. What was the biggest challenge when you learned English? The grammar.

Shay Nehmad:

I learned English, myself, and then I had to relearn it in in school. And in school, it sucked because it was like Hebrew textbooks that tried to explain the rule of gram the rules of grammar to you. Yeah. But I already knew them because I, like, played Sims and Doom and and Of course. Yeah.

Shay Nehmad:

On my on my and, like, tried to mess around with, technical stuff, on my computer at home, which was a Windows 95 machine, I think. Alright. So my biggest challenge with learning English was I actually had to unlearn it to get good grades. Yeah. But eventually, it was fine.

Shay Nehmad:

Awesome.

Jonathan Hall:

As evident or

Shay Nehmad:

not evident by this podcast. I don't know if I sound like a complete, imbecile to you. No.

Jonathan Hall:

Not a complete one. Only a partial one. For sure.

Shay Nehmad:

But yeah. This

Jonathan Hall:

has been an interesting conversation. Thanks for the topic. Thanks

Shay Nehmad:

for listening, everyone. Sort of different interview instead of an interview conversation. I just really wanted to talk about John with it, and if we're not recording, he's, like, ripping off the hair headphones and leaving to do other cooler things.

Jonathan Hall:

Speaking of it's lunch time. I'm about to rip off my headphones.

Shay Nehmad:

Yeah. And I'm gonna go sleep. Good night, everyone. Program exited. Goodbye.