Joel Clermont, host of the No Compromises podcast, shares his wisdom on the topic of good digital hygiene, as it relates to development projects, particularly the bits that aren't software.  Have you ever joined a team with poor documentation? With third-party credentials scattered all over the place?

Listen to us discuss some simple approaches to solving these problems for the people who will be inheriting a project after you.

Joel Clermont
Podcast: No Compromises
Products: https://nocompromises.io/products
Blog: https://joelclermont.com/
Twitter: @jclermont

Transcript

Advertiser: Ladies and gentlemen, the Tiny DevOps guy.

[music]

Jonathan Hall: Hello, and welcome to another episode of Tiny DevOps. I'm your host, Jonathan Hall. Today I have with me a special guest, Joel, who is a software developer who works with Laravel teams to help them to ship better software. Welcome, Joel. Thanks for coming on. Why don't you give us a little bit more of an introduction? Tell us a little bit more about what you do.

Joel Clermont: Thanks for having me. I like the intro. Short and sweet, but it's also vague. I'll give you a little more detail. Currently, I work with different Laravel teams in a variety of roles. Some of it's hands-on, some of it's more coaching and management and process automation, and things like that. Then, on the side of that, I also have been dabbling with building some products to educate for-- Not all companies or people can work with us, so, some other resources that people that want to learn. Books and some courses are coming too.

Jonathan: Where are you, by the way, Joel? I have quite an international guest list as well as audience. Where are you calling from?

Joel: I live near Milwaukee, Wisconsin, in the US. If you don't know where Milwaukee is, it's about a 90-minute drive north of Chicago. Most people know where Chicago is. I work out of my house and have been here for quite a while.

Jonathan: Do you normally work out of your house, or is that a pandemic thing?

Joel: That is a normal thing for me. I briefly experimented with having an office outside of the home, and it had some advantages, but it had more disadvantages. When we got a slightly larger home, and I could have a dedicated space here-- I've been here for the last 12 years now.

Jonathan: I've heard you talk about, on your own podcast, some practices you like to do. I'd like to just have a discussion about a particular scenario I remember you mentioning. You said that you were handing off a project or preparing to hand off a project. I guess it was a client maybe you've been working with for several years, and you are, I don't know, leaving the project, or someone else is taking over. You went into some details on some of the things you do to hand over a project. I don't know if how much detail you want to go into in that particular story, but maybe you could talk about handing off the project.

Joel: This is something that happens from time to time, and for various reasons. Sometimes it's client-initiated, like, they've worked with us for a while, and now they're going to hire some in-house people, and we're handing off to them. Sometimes they work with a marketing agency that says, "Oh yes, we can do this application stuff too." That's one reason. Other times, we just don't have the availability, or we're specialized, and we want to shed some of the projects that don't fit within that specialization.

The way I think of it, in an ideal world, you start the project with the mindset of, "Hey, at some point, I'm going to hand this off. I want that handoff to be as seamless and pain-free as possible for both parties. For both me, the person handing it off, and for the agency or company that's going to be taking it over." I've experienced the receiving end of that handoff in times when it's been, not painless, it's been quite painful, and so I don't want to do that to anybody else. The transition can already be a little stressful for the client, so I want to make that as smooth as possible.

Jonathan: When you talk about handoff, I imagine the same pain can be experienced, even if it's not a handoff per se, but maybe you're joining a new project. Like, many of our listeners probably are not freelancers. They're probably just joining a team, and they're excited to join a new team and start up a new project, but they're going to have a lot of that same pain, I would imagine. Would you agree?

Joel: Yes, it's a similar process for sure. Whether you're taking it over as a freelance person, or you're joining something that's already in progress as a new team member. Yes, very similar.

Jonathan: Maybe just briefly, to set the stage for the rest of the conversation, what are some of the biggest pains you've experienced in this situation, that you're trying to overcome with the rest of this conversation?

Joel: The one that I think would be most applicable, even within a company, a team member joining, is just lack of documentation. Here, I'm assuming you're going at least have a repository of code and not just be handed a CD-ROM or something with the source code burned on it. Here's the repo, and the first thing, there's no README, or maybe it's like the default README from whatever application framework they've generated their code from. You're like, "Okay, where do I start?"

Even if it's a project, built-in technology you're familiar with, there are 100 little decisions that if they're not captured in documentation, are not obvious to somebody joining the team. For example, how do I set up my local environment? Are we using Docker, or is it expected I have my own tooling to get set up? If I'm using Docker, is it just as simple as running a couple of commands? What are those commands? How do I see the database? How do I run tests? All these different things, they're obvious once you know them, but when you're coming in fresh, there's a lot to learn.

That's the piece of it, that documentation can really help you get over that hump quickly. A fun exercise I like to suggest, so, let's just say I've gone through the work of creating that documentation, I will then usually have somebody else, or myself again, on a different machine, follow the documentation as if that's the only knowledge I have. Usually, even just that process, I'll have missed a step or two, or there was something about my machine that was a little different from a different clean machine. That is useful too, to test the documentation in that manual process.

Jonathan: You've already started to answer this next question. What are the specific things that you tend to do to prepare for that handoff, or maybe a new person joining the team, whatever to give that context to someone?

Joel: Documentation is a big one, but it's not the only one. Sometimes even, there are some areas to explore within documentation. Everything I just referred to, is more project-centric, like, how do I make the code work? There's other things too, that are vital, especially if it's been handed off from company to company. Like, what about the operational side of things? Where is this application hosted? Who owns that account? What are the credentials to get access to that? This is the sort of stuff that really doesn't belong in a repose/ README because it might be more privileged or sensitive information.

Somebody should have a document somewhere that outlines it, and that can be part of the handoff process. That's part of it. Another thing too, that might fall under the umbrella of documentation is more like the business, and process, and architectural side of it. Not the mechanics of how the project works, but why was a particular decision made? Especially if something might be a little outside the norm, why did we choose to do this? What were the pros and cons, and the things that ultimately led us to this decision?

Developers, they come into something, and if it doesn't immediately fit with their preference or mindset, we need to change that. That's not right. Let's do it this other way. Documenting some of those decisions can help somebody coming in, not only get up to speed more quickly with the code, but with the overarching decisions that drive the business needs for that code as well.

Jonathan: What is the best time to do these things?

Joel: Absolutely at the last minute, when everybody is panicking.

[laughter]

Joel: No. That was a nice softball question. For sure, as you go, as you're working on a project, that's so true of many things, but when it's freshest in mind, is the best time to document it. It's sometimes easy to just want to move on to the next thing or think, "I'll come back and document that later," or, I've even been guilty of this, I'll sketch out some documentation. It's just an outline, and then even I'll come back to it the next week to fill it in. I'm thinking, and I'm looking back through chat logs, and through my notes, and commits.

As soon as possible, while you're doing things, while you're making the decisions, while you're adding the step to the onboarding process, while you're adding something to the codebase, try to do it as part of that process while it's happening.

Jonathan: I've been guilty of the exact same thing. I'm going through a process going, "Oh, I'll go back in a day and update that." That day never comes, or if it does, then I forget what I was supposed to be doing.

Joel: I just had something recently, this was less of a documentation of something new that was added, but more of documentation of a troubleshooting step. There was an issue in production that was having an impact on a fair number of users. Of course, Step 1 is to triage that and fix it. Then the immediate Step 2, was to document it because this was actually something that happened like 4 years before, and I had a vague memory of it. I happened to have been on the team at that time. That helped me, but I said, "You know what would help me even more, is if I had this in a document somewhere.

Troubleshooting steps. If this is happening, take a look at these four things." I created that document. It took me maybe 15 minutes after I was done, but I hope if that ever happens again, it'll save me a lot of stress in the moment. That's another form of documentation that really, really is handy when somebody new is coming on.

Jonathan: That is the worst. When you know you've solved a problem before, but you can't remember how. I imagine most people listening can identify with what we're talking about, and they can probably recognize, yes, I should do these things from Day 1, but we don't. You and I have both admitted that we don't. How do you overcome the tendency to ignore these things until it's too late?

Joel: I don't have a silver bullet, or whatever, to tell you, but in my own reflection, it's a combination of a general maturity of understanding the importance of these things, mixed with a healthy dose of the pain of not having done it. Those two things combined makes me more aware of the need and importance of it. Something else too, that again might apply a little bit more if you're independent, and you're attracting clients, but I've actually discovered it's a little bit of, it can be a competitive advantage.

Like when a customer needs a web app, and they're shopping around, I can assure you the last thing on their mind is, "I wonder how well they're going to document their code or the processes." They don't. They're not even educated enough generally to know that's the thing that's important, but in the sales efforts and things, I will sometimes even make the joke, one thing we pride ourselves on is making it easy to fire us if need be because clients have been through the pain of a handoff that doesn't go well. They know that's bad, and they know they want to avoid that.

Jonathan: I suspect that insight, extends to typical salaried employees as well. It'll be a little bit different way, but if you're working for 9:00 to 5:00 as a regular salary employee, your boss doesn't want to worry about what happens when you leave. Maybe you get some, you can gain some short-term job security by not documenting things and being the one guy who knows everything, but you're not going to earn yourself a good recommendation whenever you leave, and your boss is going to have an animosity towards you. If they know that this is the case, maybe they won't fire you right away, but they're going to be looking for a way to.

I think just being a mature person, in general, is probably good advice, whether you're a freelance independent or working as a regular employee.

Joel: Yes. I joke job security is good, but you never want somebody to feel held hostage. That's the only reason they're working with you because that's not a healthy work environment either.

Jonathan: Do you have an example of a good experience, where this has gone well for you as somebody, either taking over a new project or joining a team, where this has gone Well?

Joel: I wish I had more good experiences of receiving it, but I can share some of handing it off because we're in the midst of one right now.

Jonathan: Sure.

Joel: Maybe I'm a little biased, but I think it's going pretty well. The example, it was a mobile application iOS, Android app, and really, really good client relationship. Very happy with the client, product is successful. Launch was great, but we reached a point where we realized this isn't our core business, and there's only so many projects we can take on. We just made a decision we're not going to do any more mobile development. We had that somewhat difficult conversation with the customer and even made some recommendations.

Going through that process of the handoff, there was even some surprise expressed by the new company. Like, "Wow, I've never come into a project that was this documented." Not to toot my own horn or whatever, but part of it was because mobile development is not our core competency- we did a good job, but it's not something we do at second nature- we were extra careful to document it. Then you have all these certificates, and keys, and profiles, and things with different app store accounts and all the services. Like we use Google Firebase, and so there was a lot of different things going on there to coordinate that.

We had a giant README. I almost thought it might be too much information, but no, they were very appreciative. All the way from getting it set up, to deploying it, to spinning up a release, to all the different things. We just documented it. It made the process, which was a little difficult and uncomfortable just because we were breaking up with somebody, but it made it a lot easier for them to just take it over. The other thing, and again, I don't know how broadly this applies, but even after a handoff, I always make myself available for questions because I recognize as much as I try, I'm not going to get every single thing.

It's just impossible. That can help with a handoff too, is just a willingness to cooperate, and to be available, even if it was a client initiating the breakup if you will. I take a long-term view towards things, and I like to be respectful and professional, and so, at no cost, I'll make myself available over email, or an occasional chat to answer any questions that follow up after the fact. Even a month or two later, sometimes they crop up.

Jonathan: If I ever need a mobile app developer to fire me, I'll look you up.

[laughter]

Joel: Perfect. Maybe there's another career opportunity there.

Jonathan: One other question, where do you suggest putting this documentation? You talked about a really big README, is that the best approach, or would you put it in a Confluence page, or something like that? What do you suggest?

Joel: I'm a little GitHub-biased. That tends to be what we used, but the same principles apply, I think, to most hosted source code repositories. A README for sure, at a minimum, should direct you to where these other resources are. I think a README is also a good place for the instructions to get a project set up from git clone to running the app. I've had projects, especially longer-lived projects, where the READYOU outgrow the README pretty fast, especially when you get into more of these architectural decisions and things like that.

I like using GitHub, has a Wiki feature. I know that Bitbucket has that as well. I think GitLab does too, where it's actually a separate repository, but it's presented in the context in the UI on the website of the main code repository. It's a nice separate place to version things and have more structure, like a table of contents. Although a lot of these don't have great search tools, I found. That's a weakness, but at least you can clone it, and then it's plain text. You can search it pretty easy, but I find that works well. One project, in particular, they use Jira, and Bitbucket, and Confluence.

Because they already had some existing business documentation in Confluence, we went with that. We just created our own little space in Confluence and a table of contents there. Then it was linked too, from the README. The README said, here's how to get this project set up for this, this, and these other types of documentation links directly to the Confluence page.

Jonathan: Earlier you mentioned credentials. I don't want to go too far into the weeds here, but just generally speaking, where would you store those, if not in a Git repository? Just point people in the right direction.

Joel: I personally use one password and its Teams feature. Generally, we'll use that on the team for those sorts of credentials. Even before that, I feel very strongly, another place where developers get themselves into trouble during this handoff is they own some of these accounts. They might think, "I'm doing them a favor. I'll just stick it. I'll stick their repo in my GitHub account," or, "They're not really savvy, so, we'll just put this stuff in our AWS account, and we'll bill them for it." I don't do that. Sometimes clients don't like it, but I'm like, "No, you have to set up the AWS account, the GitHub org.

Here's how to invite me." I even have resources. They're on our website for anybody to use, but resources for how to set these things up step by step, how to invite me with the full level of access. That's the most important part is that the client owns it, and they grant access to us. I'll even include, "And down the road, if you ever need to remove our access, here's how you do it." That's part of the same document, to just give them a sense of security that they're in control. I can't tell you how many projects I've come into where DNS or even owning the domain, like the developer just did it--

Again, I never assumed malicious intent. They were probably just doing it to expedite things or to be helpful, but wow, that can be pretty gnarly to untangle. Especially if it's ending, if the relationship is ending on a bad note, then there's less incentive for them to cooperate, and it can be really dicey situation. For the day-to-day sharing of credentials in a team, something like one password, or last pass they have team accounts. That first step, make sure the client owns their access first, is absolutely critical.

Jonathan: Is there anything else that you think is worth considering in regard to keeping a project ready for the next person?

Joel: Yes. One thing I would add, especially if you're on a team is, generally, these sorts of things are best accomplished if there's total buy-in from the team. If one person on a team of five developers is devoted to documentation, but nobody else is, that's an uphill battle. Partial documentation is better than none, but it can be pretty discouraging to the person trying to do it if not everybody is. What I've found helpful, even if there's initial pushback, is to make it part of the code review process. When a pull request comes in and there's a new feature added, or something brought into the project, to just verify. on a checklist or something, was this documented? Was this decision captured somewhere? In the case of a new service coming on board, were the credentials captured in a place that can be kept safe by the project lead or the team lead?

That you said, it's not controversial the idea of doing it, but sometimes in the heat of development, people can be resistant to wanting to do it because we all have more work than we can get done in a day usually or more work that we want to get done than we can. If you don't really value this, it might seem like extra, or a time-waster, or something I'll do later, but working it into even the code review process, I found to be helpful as well.

Jonathan: If people are interested in learning more, I know you have a podcast, what else do you have to offer if people are interested in learning about these topics?

Joel: The podcast is generally a starting point. Our target audience in mind is a developer working on a product team. That's our focus, but it does apply more broadly, so, check that out. The other thing too, I think I mentioned at the top, is some of our products, some are free, some are paid, but on our website, there's a /products link that you can go to that has that information. You can even sign up to get notified when we publish new things too.

Jonathan: What's the website address?

Joel: nocompromises.io The website for the podcast is show.nocompromises.io, but yes, that's the main hub to get access to these different things.

Jonathan: Great. Your podcast is directed primarily at Laravel developers, but even though I'm not a PHP developer, I still enjoy listening to it. I think I've only skipped two or three episodes that were very PHP-centric. Don't turn away from his podcast, just because you're not a PHP developer. It's still an interesting show to listen to.

Joel: Yes. We have a particular audience in mind. Like you said, some episodes veer more heavily in the weeds, that would be more specific. Even if we're talking about something like validation or things like that, most web frameworks have these same concepts, so, we're mainly sharing opinions. A podcast isn't a great way to actually talk about code in the specific $var =. That's not real productive. It's more principles, opinions, things that we've learned, either the hard way or from others in our journey as developers.

Jonathan: If people are interested in contacting you, what's the best way to do that?

Joel: Probably the easiest way would either be through my site, joelclermont.com. That's the French spelling, C-L-E-R, joelclermont.com, or my handle on Twitter is @JayClermont, same spelling.

Jonathan: Thanks again, Joel, for coming on. It's been a pleasure talking with you. I hope we've encouraged a few people to document their projects.

Joel: For sure. Maybe it's somebody who's listening today that'll hand off a project to me in the future, and it'll all just come full circle.

Jonathan: Wouldn't that be nice?

[music]

Jonathan: Do you have children in your life? Would you like to be able to more effectively communicate with them about the work you do every day in IT? Join me and children's book author, Miriam Tocino, this Wednesday, June 23, for a free storytelling workshop. We will break down the complexities of our work on servers and software in a way that we can communicate more effectively with children, or for that matter, anybody else who's non-technical. I hope you'll join us. Visit jhall.io/story for more information. My thanks to Rodney Day for the Tiny DevOps theme music.

[00:24:19] [END OF AUDIO]