Hi and welcome back to Weekly Dev Tips. I’m your host Steve Smith, aka Ardalis.
This is episode 56, on the importance of having a simple way to build, test, and run your application locally.
One Step Build Test Run
This week's tip is brought to you by devBetter.com.
Sponsor - devBetter Group Career Coaching for Developers
Need to level up your career? Looking for a mentor or a the support of some motivated, tech-savvy peers? devBetter is a group coaching program I started last year. We meet weekly for group Q&A sessions and have an ongoing private Slack channel the rest of the week. I offer advice, networking opportunities, coding exercises, marketing and branding tips, and occasional assignments to help members improve. Interested? Check it out at devBetter.com.
Show Notes / Transcript
I've worked on a lot of projects for a lot of different companies and teams. One thing that dramatically increases the friction of becoming productive on a project is the number of manual and often undocumented steps required to take a new developer on a new machine and get them up and running the application from its source code locally. A lot of the time the developers on the team don't even recognize this as an issue because they've all been there long enough that they've absorbed the knowledge that's been passed down through shared oral history since the ancient times. But new developers, and especially new developers on distributed teams, weren't there last week when someone said "Oh yeah, I changed this thing so now you have to install this tool before you run the app on your machine". They don't just magically know the arcane command line scripts that must be run from 4 different nested subfolders of the application's source code in order to get the system up and running. As soon as you have one new remote team member, it exposes all the implicit knowledge-sharing and manual steps that have taken root in the team's processes and, hopefully, forces the team to make these steps explicit and then to automate them as much as possible.
Simple projects don't require much, if any, documentation or automation. If you have an application that is so simple that any new developer can pull it down from source, use the default compilation step for the platform, like dotnet run for .NET Core or F5 for a Visual Studio-based solution, then you may not need any more documentation or automation than that.
But when it's not that simple, you'll make everybody's life easier if you document and automate the steps. Documentation should be first, since it just makes the steps explicit, and sometimes automation can be difficult to achieve, especially if you need it to work across different operating systems. This is getting easier, though. Once you have the steps documented, you should strive to automate them to the point where common tasks are a single step. Ideally you want a One Step Build Test Run script that does all of these things: builds the app, runs tests against it, runs the app.
But before we get that far, let's talk about how to document the process a bit more. Today, GitHub has become the standard for open source software projects. And GitHub has essentially codified the standard that projects should have README.md files in their root that describe what the project is. Even if you're not hosting your application's code on GitHub, it's a good guess that your dev team has looked at projects on GitHub and is familiar with this convention. Thus, purely from a discoverability standpoint, the best place to put important steps for building and running your app is in its README file in the root of the repo. If you have a lot of repositories that all use the same steps and you don't want that duplication, then put a link to the shared docs into each README.
What about wikis? Wikis are less discoverable. They're not right there in your face when you hit the home page of a repo, and they're not right there with your code when you're looking at the source in your favorite editor like a README file is. You can put more detailed documentation and steps into a wiki if you like, but to make it discoverable you should put links to it in the README file. If you use some CMS system or project management system the answer's the same - use the README as the place to include the links to the relevant information so new team members don't have to try and find it themselves. HTML supports hyperlinks for a reason.
Probably the worst thing you can do in documenting your local build/test/run process is to start by putting it in the README file and then later decide to put the process in a wiki or another location, but not update the README. This will cause team members to use the README and not discover the new location, wasting lots of their time. Bad information is worse than no information. Put a link to the new process documentation location in the README.
Show Resources and Links
That’s it for this week. If you want to hear more from me, go to ardalis.com/tips to sign up for a free tip in your inbox every Wednesday. I'm also streaming programming topics on twitch.tv/ardalis most Fridays at noon Eastern Time. Thank you for subscribing to Weekly Dev Tips, and I'll see you next week with another great developer tip.