How long does it take to get your project running?

Aaron and Joel have joined a fair number of projects over the years. Listen as they share some tips on how to make process less painful for your team.

Sign up for our Laravel tips newsletter!

Creators & Guests

Host

Aaron Saray

Host

Joel Clermont

What is No Compromises?

Two seasoned salty programming veterans talk best practices based on years of working with Laravel SaaS teams.

Joel Clermont (00:00):
Welcome to No Compromises, a peek into the mind of two old web devs who have seen some things. This is Joel.

Aaron Saray (00:08):
And this is Aaron.

Joel Clermont (00:16):
One of the joys of joining a new project is, in addition to figuring out how everything works and what the code does and things like that, you have to get the code running on your machine if you're going to contribute in any meaningful way. I've joined projects where that was a breeze and I've joined projects where it was a nightmare. So I thought maybe today our topic could be our experiences, things we do to make that process better, why it's important. Just kind of hash that out between us and hopefully share something of value.

Aaron Saray (00:48):
Yeah, that is something that I find very interesting. Because it's one of those topics or one of those things that it's like you always strive to be better at it but never seems to get perfect. Like you said, I've worked on projects where it's really hard to get up and going and I've worked on that's relatively easy, yet it was never just point and click. You know, there's always something. You're always a little bit off. I can think of two different reasons why that might happen. The first is maybe environment specific if we're using tooling or environments that are similar or the same. It could be even as much as different OS versions on your local computer, all that kind of stuff. Then the second would be documentation. If people are keeping instructions up to date. And the idea that we don't have to document something because it's so easy to do, that's not true. That's never true.

Joel Clermont (01:42):
Yeah. You kind of said something by the way, not only writing documentation, but keeping it up to date. Because that's almost worse than no documentation. Is, run these commands and none of them do the thing they're supposed to do.

Aaron Saray (01:56):
Well, I think that's something I kind of want to dig in on here then. I think that there is a responsibility of someone, like the lead developer, to start out the first documentation. At some point, it has to be part of the project cycle where I'm going to document how we get our application working for a new employee, whether or not they're coming along. I mean, it's almost better to do it if someone's not coming along right away, because then you can distribute that work into your workflow. Versus, "Oh, I have all this work to do. I have due dates and someone's starting tomorrow and I have to document all this."

Joel Clermont (02:28):
But you don't let the new person be the guinea pig and have them document it as they're figuring it out?

Aaron Saray (02:33):
Well, that's actually my next point though. Is you get it going and then I think the next thing is there's no way that one person reading documentation someone else wrote, especially if it's someone like the senior developer who can make tons of assumptions, is going to be able to get all of that stuff out there. Probably still going to have questions, so I think it's the responsibility of the person who's then following them, following those instructions and documentation, to update it with things that they didn't understand. Or maybe things have changed since last time these steps were ran. Or, for example, if everyone uses Windows and then a person comes on with Mac and most of the things are the same but some are different, even if they can make that mental leap themselves, they still should document that for another person who comes on who maybe knows Mac but doesn't have as much prowess converting those back and forth.

Joel Clermont (03:26):
Yeah. And I like that point about it's kind of a team responsibility. So, if you run into something in the docs that aren't quite right, instead of just like grumbling and moving on, update the docs, put that in the notes and share that. Especially with, you mentioned an assumption. I'm assuming this hypothetical lead dev doing this exercise didn't go out and wipe their machine or buy a fresh computer, so there's probably some tooling or some password set up already somewhere that it's a step that's not going to get captured in the docs and the poor new employee is going to bump into it. But working together, it can become a better, more robust piece of documentation.

Aaron Saray (04:08):
Now I can hear myself years ago kind of already starting an argument with us and saying like, "I don't have time to do documentation updates if something isn't good." Or, "My boss doesn't curve out time to make that happen," or all these different. You'll call them reasons but they are excuses. I'm going to label them as excuses but I'm going to give you a tip. This is a tip that I've used many times and kind of helps out when you're in these situations. It's, do it anyway and then share the updates that you did it on some sort of team meeting. It's really difficult... I mean maybe this has some sort of evil mind trickery, but it's really difficult for the boss to chastises you in front of the team for doing documentation.
If you know it has to be done, then you share it in front of the team that it was done. It was done and now the team can possibly open up a conversation and say, "Oh, yeah, we should do more of that." I'm not saying that there's evil bosses out there, but sometimes they lose track of what's most important. And this is one way I've seen as ways to get the documentation done when it needs to be done.

Joel Clermont (05:18):
Realistically speaking, updating the docs isn't the thing that's taking the time. It's figuring out what was missing in the docs and kind of coming to that conclusion.

Aaron Saray (05:27):
Right.

Joel Clermont (05:27):
So you could even argue, "If you don't write it down, you're wasting more time for the team overall for the next person that has to go..." Maybe it took an hour to figure it out and 10 minutes to update the docs, now that hour is going to get repeated next time. But I like your strategy, I might have to use that on you sometime, Aaron, if we're in a team setting where I'm trying to do something I know you don't like. I'll pull that one out. Now we've talked a little bit about documentation but it might be worth talking a little bit about the tools or the ways to actually go about making this environment easy to set up or reproducible. What are your thoughts on that kind of... Every situation will be a little different, but some general go-to tools that you like to use?

Aaron Saray (06:13):
I think my opinions of this kind of changed as I became a contractor or had more experience jumping from job to job. Because when you think about maybe the... You get a computer and maybe you work at a company for five, seven years and that's what you use that computer for, it might be easier just to standardize on that computer. But if you're a contractor and you know on day one, I have to spin up this one client stuff and this one's on PHP 7.4 and this one's on 5.3 for some reason. You're trying to juggle this stuff back and forth, it becomes a little bit more important to containerize or encapsulize those things separately. I don't want that to be confusing thinking that if you only work for one company, that you should just use your local computer either. Because operating system updates, you might install something differently. Even as much as if someone doesn't do an update and now that package is no longer available and that is only updated because it's patched and et cetera. I mean, we've all ran into that.

Joel Clermont (07:20):
Sure.

Aaron Saray (07:20):
Every once in a while you run into that. Something with Composer and you're like, "This package isn't available anymore." Well, imagine that with the base PHP and Nginx and all those things on your computer. I think I'm more in favor of, even if this computer's sole job's that do this one thing that you still figure out a way to encapsulate all of that environment into something that is the same for every single developer.

Joel Clermont (07:49):
Yeah. I mean, for me, kind of the classic thing before I went down this path was like you mentioned, the operating system upgrade. Sometimes I'm on a Mac, so sometimes it would be like Xcode developer tools or something would change version and then all of a sudden node doesn't compile the SaaS library properly and it spits out some really obtuse message, and you burn half an hour to an hour getting that back on track. So encapsulating that sort of thing too, those pain points go away. You're inheriting maybe a different set of pain points, but I still think it's a valid tradeoff for sure.

Aaron Saray (08:23):
When we talk about encapsulation, what are some of the tools that you might use to do that?

Joel Clermont (08:29):
Well, my current go-to tool is Docker. I've found it useful that... There was a learning curve, so I started down this path by trying to use a pre-generated Docker environment that was for Laravel and that was all right. Then I think I adopted a Laravel Docker template you put together and just inherited it and then I would ask you if I got stuck. Then only recently, I started to dig in a little bit more and kind of really understand what was happening. When I needed to change things, it wasn't a total black box to me. I'm still on that path of, I certainly don't think I've mastered Docker, but I've gotten proficient enough in it that it's my go-to tool. And when I between machines, or like recently, I updated my OS, I wasn't as afraid as I was in the past because I knew these things would continue to work. But that's currently my tool of choice.

Aaron Saray (09:24):
I agree. I use Docker most of the time but I would kind of caution that it's not the overall solution for everything too. Because one of the things that we preach is try to work with versions and configurations that are as close to production as possible. When you're working in a set of containers with certain versions of things that's close, but that may not be the exact same situation that you have on your server. I'm thinking about situations where maybe you deploy something to DigitalOcean using any of the tools in the ecosystem, like Forge or something like that. In those cases, I will also consider, "Am I deploying this as something that can understand containerization or is it better to use a configuration like Vagrant and Ansible?" Kind of like how Laravel did Homestead for a long time too. If this is going to be more of the exact configuration I'm going to be deploying.
For example, if I'm going to be deploying a server that has Redis and MySQL and Nginx and PHP all installed in the same box, I might provision of a Vagrant and Ansible version of that. Whereas, if I'm going to be deploying something maybe that has an Nginx proxy and then has a manager Redis and has managed MySQL and stuff like that, I know that those are... They're not the same as my containers but they're remote and they're different and they're encapsulated. I might then locally use Docker.

Joel Clermont (10:51):
Yeah, I do that too. Because I'm not at the point where I'm deploying using Docker. But what I will do, let's say I have a Forge managed VM, and you can click a button and get the next version of PHP or even a patch version. Before I do that, I will update my Docker instance to that exact version I'm going to go to, so it's a new patch version of 7.4. Similar with updating MySQL, I generally would use the managed service like RDS, and it gives you control over what version you want to run. I don't let it just auto update when there's an update available. I first do it in my Docker container locally, rerun my test and then I'll do it. It's not technically in sync but by convention I sort of manage it that way and use that flow and so far it's worked pretty well. It has caught some things locally that I didn't have to find the hard way in production.

Aaron Saray (11:45):
I think the last thing I'll bring up here is that another thing is the planning of how you might introduce someone to the code now when it's running. I've seen a lot of people say, "Well, I'm going to give this new developer a job that touches a lot of spots inside of the application, so they get familiar with the application." If they have to adjust this, they're loading all these pages and we forget that feeling when we first started into a project. Which is OMG panic, right?

Joel Clermont (12:15):
Yeah.

Aaron Saray (12:15):
"I don't know what's going on here." So it can take a while to even understand how one feature works. And with the new developer, now you're saying, "Try to figure out real quick how six features work, make small little changes." And they're trying to show you they know how to do stuff or whatever. I'd say one of the things I'd finally preach is, we have documentation, we have containerization or same environments. Then I'd say the final thing is, give someone a very singular, measurable task that's more of a silo than spread all over so they can learn one thing and you can see how fast it takes someone to learn one thing in your code base. That's much more useful than saying, "Scatter yourself all over." Because, especially if you're only touching the top level of everything, you still don't know how fast it's going to take them to dig into something that's actually more complex.

Joel Clermont (13:09):
Yeah. So you're not an advocate of just throw somebody in the deep end and not help them up?

Aaron Saray (13:15):
Well, yeah. Right in the deep end but just hold them in that one spot then.

Joel Clermont (13:20):
Just one deep end, not a whole bunch of deep ends.

Aaron Saray (13:23):
Yeah. I want them in the deep end, I don't want them in a bunch of shallow pools.

Joel Clermont (13:27):
Okay, interesting.

Aaron Saray (13:29):
Yeah.

Joel Clermont (13:35):
Aaron, you and I spend quite a lot of time in meetings and generally we like to have our meetings over video conferencing. In other areas of my life, I've spent a fair amount of time on video conferencing lately as well. There's this thing I've noticed that can be a little awkward and I'd like your advice on it. When you're ready to hang up the call, there's always this weird panicked dead stare when you're searching for that button. Lately, I've taken upon myself to figure out the keyboard shortcut to exit because that way I'm first one out and I'm not that guy stabbing at his iPad or looking for where Zoom moved the button this week. What's your strategy? Or, do you have any observations along those lines?

Aaron Saray (14:26):
Yeah. I don't know if it's the stare, it's more of the down look.

Joel Clermont (14:31):
Okay, yeah.

Aaron Saray (14:31):
It's like you're making eye contact and then everyone says, "Bye," and then everyone looks down to the right hand corner. I should take a Brady Bunch screenshot of this at some point. Actually, I think what we should do is the equivalent of, "No, you hang up." Which is when you say bye, just keep staring forward. At some point you're going to be the last one on the call and then you can look all over as you try to close out the window.

Joel Clermont (14:58):
We've turned an awkward situation into a confrontational feat of strength to see who will buckle first?

Aaron Saray (15:06):
This was really my middle name.

Joel Clermont (15:10):
I like it.

Aaron Saray (15:11):
Oh, that looks uncomfortable. Let me make it into a fight.

Joel Clermont (15:16):
"All right, well, I'll talk to you later." Then you just sit back and you just look at them. No movement toward the mouse or anything at all.

Aaron Saray (15:23):
Oh, if you could flare your nostrils that's even better. No, seriously, I ended up... I saw that too and I ended up making an Alfred Script with that, "Interact with Apple Script to click this buttons." Turns out there's a shortcut key but I didn't realize that. I had this super complex thing that I can just make it look like I'm just typing something and closes. But I will tell you, there was one or two times where I also... I knew I was having that problem, so I would go and move my mouse and hover over the leave button and get it ready to go.

Joel Clermont (16:01):
Armed and ready.

Aaron Saray (16:01):
Yeah, that worked nine out of 10 times. The 10th time being when I accidentally just clicked for no good reason when I moved my mouse there and left the call early. But, I mean, yeah, it's a problem and I think we've given everyone some solutions to that.

Joel Clermont (16:17):
Well, in worse case, if you're panicking just rip the power cord out of the wall and you're done.

Aaron Saray (16:23):
In this episode, we talked a little bit more about the theory of things, but if you're looking for a little bit more hands-on code related tips...

Joel Clermont (16:30):
We can help. Check out our weekly newsletter at nocompromises.io/tips.