DEV Community: Paul Cullen Rowe

Onboard New Developers Faster With This Guide

Paul Cullen Rowe — Thu, 14 Oct 2021 14:02:12 +0000

Are you tired of having to hold every new developer’s hand and watching them struggle to get up to speed with your team?

Onboarding new teammates should be fun and easy, for everyone involved.

I've lost track of how many developers I've onboarded to my engineering teams. Though important, this process is very often a pain point that sucks time away from my day-to-day responsibilities. Or at least that was the case until I created the “Zero to Deployed” guide for our team. This guide has streamlined the onboarding process so that both existing and new team members can complete necessary training and get up to speed as quickly as possible. That way, onboarding transforms from a drain on resources to a streamlined process that allows everyone to focus on their primary responsibilities in a timely fashion.

The "Zero To Deployed" Guide

The “Zero to Deployed” guide walks a new dev through every single, tiny step from the moment they open their laptop until the moment they deploy a feature. We write it with deep detail so that a junior developer can follow the steps without asking for help.

We immediately saw this pay off — our onboarding time (for us, this spans the moment new hires open their laptops until the moment they create a PR) went from one to two weeks down to two to three days. The process also involved significantly less hands-on assistance from team leads. We then broadened the guide to apply to all engineering teams across our organization, and the benefits immediately scaled.

Below, you can find a rough outline of what we include, how detailed we get, and you can use this as a template to develop your own version.

Beyond The "Zero To Deployed" Guide

Before we look at the guide itself, however, we need to consider a few important ancillary documents. After all, there's more to your codebase than just the setup. So, we include some other complementing documents with the guide itself:

The Core Concepts Onboarding
Rules and Guidelines

The Core Concepts Onboarding is a high-level overview of the tools in your product and the main components of the applications. The aim with this document is not to be exhaustive, but just to give the new team member enough context and guidance to be productive. For example, it might include what a fully-baked React Component usually looks like, how our app uses some crucial library, how our app interacts with other apps/services, and the main features of our application (or suite of applications) to name a few items.

The Rules and Guidelines set the practices and standards for the codebase, acting as a how-to guide for the code that we write. For example, this document details our git management strategy and merging rules, our rules around redux patterns, unit testing guidelines, code style rules, and things to look out for during code review.

These can all be compiled into one document or spread out over many smaller ones. The important thing is that the guide is easy to reference and clearly teaches your new teammates how to write code in your repository. It also helps if you can create links directly to certain content in these documents (with header anchors or separate pages) so you can easily share relevant information later during code reviews.

Maintaining the Guide

Every time we onboard a new developer, we also give them the power to edit the guide. As time goes on, steps change, and it may come to contain outdated information or be missing new material. The new team member is responsible for finding the new information and updating the guide so that future developers don't run into this same roadblock. This is usually the only time that managers are required for assistance in order to find that information, and becomes an increasingly rare occurrence as the guide matures.

An Example "Zero To Deployed" Guide

Here's a high-level example of our Zero To Deployed Guide, so you can understand and create one for your own team.

Note: In our real guide, each bullet point includes detailed commands, instructions, and examples for successfully performing that step.

Dev Setup

Figuring out the best environment for developing our app usually matures with time, as we discover which tools most effectively help our development process. We can fast-forward this discovery experience for our new teammates by explicitly walking them through setting up every tool that has been making us productive for so long.

What logging into your computer for the first time involves
- Step-by-step instructions for getting logged in, and what applications you need to log into
(If needed) How to request access permissions for software/environments
When you open your computer, install <these things>, using <these commands>
- Homebrew, git, etc.
- VSCode, Postman, Chrome, etc.
  - Required and recommended extensions for each app
Clone the repo, then install dependencies
- Step-by-step guide for cloning, setting up git credentials, etc.
How to Run the app
- Include main flows for them to experience to validate that their application is running smoothly

Building a Feature

Every development team has a different process for taking a feature from ticket to merged code. Here, we set up a step-by-step walkthrough of this process, and what to expect as they reach each step.

How to Create a feature branch
- Typical root branch, branch naming
How to Test the feature
- Unit testing, manual testing, dependency testing
How to Submit a PR
- Rules around titles, descriptions, and build pipelines
- What to expect during code review
How QA Tests your feature
- This gives context on what kind of feedback they'll be receiving from QA
How to Merge the PR
How to deploy
How to validate a deployment

Supporting Guides for our organization

Our supporting guides are our source of truth for all practices and patterns. We make these as easy to access as we can, so that links can be shared directly to the relevant content. Our developers continuously update these guides as they come across new issues or develop new patterns.

Resources
- External links for training modules
- Important links within the organization (Confluence, JIRA, etc)
React Practices (Core Concepts)
- There are lots of ways to build React applications, here's our pattern to follow
Typescript Practices (Core Concepts)
- Typescript is still new to a lot of people and documentation is overwhelming. We include the important parts for our applications
Styling React components (Core Concepts)
- How we use libraries and reuse component styles
Unit Testing Practices (Core Concepts)
- What to test for, how to test for it, and the most-used methods
Redux Practices (Core Concepts)
- Defining our patterns around redux, and giving examples of the most common cases
Git and Pull Request Practices
- Rules around branch naming, PR rules, and code review guidelines

At Method, we design, strategize, and build all types of software for our clients. Beyond just delivering a quality product, our duty is to teach our clients practices to leave them stronger as an organization. This is one that has proved extremely successful.

The Code Review Checklist ✅

Paul Cullen Rowe — Thu, 12 Nov 2020 16:26:17 +0000

Of course, we don’t review code while walking down the hall. Yes, this is staged. There isn’t even coffee in that cup.

Code review is the most effective teaching tool for onboarding team members, upskilling newer developers, and becoming an expert on the product and technology.

But it isn’t effective if you breeze through it.

Code Review should take a good amount of time, longer than you’re probably comfortable with. The reviewer should understand what is being changed, why, and how it was resolved. Once these are understood, the reviewer can effectively critique the work.

On my teams, we prioritize quality over speed. Ironically, we often end up delivering faster than teams that prioritize speed — and with significantly fewer bugs.

Code Review takes a significant amount of time invested up front, but it creates a shared knowledge that eliminates tons of basic mistakes down the line. Ultimately this saves tons of time and effort for everyone.

Here’s my code review checklist for these teams:

✅ Understand the original problem

Whether a feature, a bug, or an enhancement, understand WHY we are doing this work in the first place.

Review the work’s ticket (if there is one) and understand the requirements
Talk to the developer or the reporter if further clarification is needed

Answer the question: “What’s the problem that this work solves?”

✅ Locally replicate the problem

git pull develop
npm start

Take the branch that the PR branched from, and physically watch the problem occurring.

When you can see what the problem is, you can diagnose the proper solution more effectively.

✅ Understand the required fix or feature

Based on what you’ve seen so far, what would you determine are the possible solutions? Try to think of a few options.
What areas of the code might need work to solve this problem?
From a UX perspective, is the solution that was proposed in the requirements actually the best way to fix the issue?

✅ Review the PR directly (understanding dev’s approach, checking syntax errors)

Now we start looking at code. Review the code’s diff in your repository (Github, Bitbucket, etc). This is the easiest way to see the “before and after” of what’s been changed, and the major pieces of the work.

Is the overall approach a good one? Is it adding too much complexity? Is it working on the right area of the code?
If so, are there any basic mistakes? Syntax errors, poorly named or mistyped variables, extraneous comments, formatting issues, or typos?
MOST IMPORTANTLY: Do you understand everything about how this code works? If there’s something you don’t understand, you should add a comment asking for clarification! This will either a) help the developer teach you new tools, or b) help them realize that their code isn’t clear and needs to be cleaner.

✅ Locally play with the PR branch

# on root branch
git pull
git checkout the-pr-branch
npm start

Pull down the code and see the solution in action, explore how pieces are being linked together and how interactions work in the code.
Try to break the feature again.
Change some code and see how it changes things.
See if there are any lingering errors in the console or IDE which need cleanup

These are all steps you will take to confirm that the code works as expected.

✅ Check if unit tests are testing every interaction effectively

Every codebase should have unit tests, and those tests should check that every function is working exactly as expected with both “usual” input and “unusual” input.

Are you actually testing everything you think you’re testing? Code coverage tools like Jest or SonarQube are easy to implement and can tell you if you are truly testing everything — I personally like a coverage level of 80%.

For each test:

Check if the output is correct with good values. Check that function handles bad values gracefully.
Check that all logic inside of a function is being tested effectively. Is something inside of a function hard to test? It probably needs to be pulled out into a separate function and tested separately.
Check that all unit tests are passing and not throwing odd/unnecessary errors in the test suite.
Check that your code coverage level has not fallen below the coverage threshold you configured. If it has, add more/better tests where the report identifies weak coverage.

✅ When you’ve given feedback, do it all again when changes are pushed

You have reviewed one PR, and it probably took a while. Good! But it doesn’t end here.

When the developer pushes new commits to address the feedback of you or others (fixes and improvements), you should go back and test it again. When small things are changed, it can have a big impact on other areas of the application. Run through the checklist again.

The code in a PR should always be considered “ready for production”, never accept “I can fix that later”. It should always be reviewed expecting a high quality of delivery.

🤔 Conclusion

This process takes a while and is intentionally intensive. That’s a good thing!

When you follow this process:

Fewer bugs get through
Developers understand more deeply about the product and learn it MUCH faster
Reduces the amount of “re-reviews” because — when done effectively — devs learn from each others’ mistakes in other PRs. This dramatically speeds up time that PRs spend “in review”
The team develops a culture of constant improvement and peer mentorship

Those are all ultimately goals of every software development team. So put better PR review practices in place, embrace the initial heavier load, and watch your team’s quality of output improve dramatically!

Paul is an engineering manager at Skookum, a former UI/UX designer, a snowboarder and golfer in Colorado, and apparently a dev blogger. Follow me on LinkedIn, the Tweeter, Github, or anywhere you can find deep snow.

Need help building a product or a team? I’ll chat with ya on LinkedIn.

How to 10x Your Speed (For anyone that uses a computer)

Paul Cullen Rowe — Mon, 19 Oct 2020 14:02:46 +0000

3 Tips to 10x Your Speed (For anyone that uses a computer)

I’ll bet you think you’re fast. I’m going to give you some tips that will make you faster, and you’ll like your computer a whole lot more.

TL;DR — If you read nothing else in this article, the takeaway is to reduce your reliance on your point-and-click mouse/trackpad , because its slow and often inaccurate.

1. Ditch your mouse, use keyboard shortcuts for everything

Let’s run a quick experiment.

Type your mailing address into some app. Then when you’re done, without touching the mouse or trackpad, try to spot your mouse on your screen.

It probably took you a couple of seconds to find it. But while you were typing, you didn’t even think about where those keys were located. They’re always in the same predictable place. Your keyboard is your fastest way to tell the computer to do something.

For a simple example: Time yourself hitting Cmd+C, Cmd+V to copy/paste. Now time yourself to Find Your Mouse > Edit > Copy, Find Your Mouse > Edit > Paste. Or even the same with the right-click menu. And that’s not mentioning time lost with missed clicks.

By using keyboard shortcuts, you save seconds on every action. Those many little seconds add up to many minutes per day, and in a week can add up to hours.

Starting today, make every effort to ditch your mouse

Keep your hands on your keyboard and don’t let them leave. Be hard on yourself, and only use your mouse if you absolutely can’t figure something out. (You should google that action’s shortcuts and keyboard it next time!)

This is going to be a very uncomfortable process and you will feel very slow for a week or two. And you’ll have a harder time when surfing websites (but don’t let this deter you, try your best, especially if you’re a software/web developer!)

Learning this skill will dramatically increase your speed!

My most-used keyboard shortcuts that people forget (mac):

In text, Option+Arrow — skip to end of word/paragraph. Option+Delete deletes whole words too.
In text, Cmd+Arrow — skip to end of line/page. Cmd+Delete deletes whole lines too.
Cmd+Tab — quickly switch apps
Cmd+Space — App/File finder (way faster than navigating through your file system, just start typing the name!)
Cmd+~ — Next window in the current app (like switching between open word docs)
Ctrl+Tab — Next tab in current window (like switching between chrome tabs)
(For developers) Learn Vim! VSCode has a great Vim emulator and it increases your development speed like crazy.

2. Only use full-screen or half-screen

If your screen looks like this, you might as well get a smaller screen

Figure 01: Small windows on a big screen are wasted space

Always use ALL of your screen real-estate so that you can see more, do more, and be more productive.

Figure 02: Using full screen real-estate with two windows via a window manager!

How? Use a window manager!

Window managers create keyboard shortcuts (ayyyy!) to snap your windows to full screen, half screen, third, quarter, any screen configuration you want, super quickly and easily. No more click and drag because mouse accuracy is slow and difficult.

Rectangle (easy, free, and successor of the late great Spectacle)
Moom ($10, lightly-customizable)
BetterTouchTool ($9, advanced, more configurable and does way more than just window management)

3. Use the desktop app of your web apps

Lots of our favorite web apps have desktop apps — Slack, Spotify, Todoist, etc. Sure, their site works great in Chrome, but it gets easily lost in all of your Chrome tabs!

The desktop app keeps a separate area of concern for each piece of your daily workflow, rather than mashing them all together in your browser. This makes it easy to quickly Cmd+Tab to your chats, or your music, or your code editor.

Plus, most desktop apps come with a few extra features that you can’t get out of the website (including keyboard shortcuts!).

So go download the desktop app for your daily tools.

But my thing doesn’t have a desktop app!

😱 Busted!

Just kidding. Things like GSuite, Asana, Trello, and your regularly visited websites, don’t have desktop apps. But there’s a way around that!

Shift — Free/$99ann. A desktop app to manage hundreds of web apps (that don’t have desktop apps) from one organized place. Check this out for sure.
Station — Free. A Chrome extension to quickly navigate to recently visited docs, tabs, sites, apps, and more. I loved their desktop competitor to Shift, but their new extension looks promising.
Fluid — Free/$5. Creates a devoted desktop app for any website. For some sites, this tool can be clumsy, but for many its seamless. Worth a shot if you want a devoted desktop experience.

— —

Got more tips and tricks? Drop them in the comments, I’m always learning new ways to get faster!

A `zsh` script to make git squashes easy!

Paul Cullen Rowe — Fri, 22 May 2020 17:32:30 +0000

Keep a clean git source tree and squash your branches before merging!

This script squashes all commits on your branch.

When you look at your main branch’s git history, in most development environments it is more useful to just see commits for major changes, not all the little steps and mistakes it took to get there. A “squash” in git is the term used for combining past commits together, thereby reducing the amount of commits in your git history.

In most of my repositories, that means when I’m done building on a feature branch, I squash the branch down to one commit, rebase the feature onto the latest original branch (master, or develop in gitflow), force-push and merge.

This makes my git history of the main branch only show commits of the finished product of branches! I use this script all the time.

(Note: Most repository managers like Github and Bitbucket have a “squash and merge” option for merging Pull Requests. This is for those who are not using Pull Requests or do not have that option)

If you use zsh in your terminal (and you totally should), this simple script will work great for you.

Copy and paste this into your ~/.zshrc file (I put it just before my aliases are defined):

squashon () {
  # If user just enters 'squashon', give help text
  if (( # == 0 )); then
    echo Hello!  This will squash your current branch down to one unstaged commit.
    echo Use by typing 'squashon rootBranchName' (not current branch name)
    echo usage: squashon develop
  fi
  # If a root branch is provided, run the squasher
  if (( # == 1 )); then
    branch=$(git symbolic-ref HEAD)
    echo Squashing all commits from $branch
    git reset $(git merge-base $1 $branch)
    echo ------SUCCESS!------
    echo Commits successfully squashed, all file changes are unstaged.
    echo Run 'git add -A' and 'git commit -m "your commit message"' to add your squashed commit.
  fi
}

What `squashon` does

Assume you have a root branch called develop, and a feature branch called feature/new-thing which originated from develop. Your feature branch has 10 commits on it, the feature is complete and approved, and it is ready to be squashed!

Run the script in the terminal with: squashon develop

This will take all changes you made on your branch, bring you back to the point when you branched off of develop, and keep them as unstaged changes.

Now just run git add -A && git commit -m 'your commit message' and you’ll have one single commit that includes all of your branch’s changes!

Note that you will need to force-push if you already pushed up to your remote, because you are rewriting the git history on this branch. git push -f

Tip: How to view localhost web apps on your phone

Paul Cullen Rowe — Mon, 29 Apr 2019 15:39:14 +0000

Dev Tip: How to view localhost web apps on your phone

I’m always building web application products that need to be optimized for mobile. Viewing my project on a phone before deploying is a must.

I often use the mobile device emulator in Chrome Devtools for little style adjustments, but there’s nothing that will perfectly emulate an actual mobile browser better than the mobile device itself. This helps me catch mobile-specific bugs before they surface as a problem for users.

Here’s a method I use to make testing on mobile devices extremely easy. These instructions are for a Mac environment.

Serve over your wifi via local IP

This sounds complicated but its actually really easy.

IMPORTANT: Make sure that your dev computer and your mobile device are connected to the same wifi network.

Step 1: Serve to Localhost

On your dev machine, serve your application in whatever way you usually do that serves it over a localhost address.

Make sure to note what port number its being served on. In the image below, we’re noting 8080.

Once you are able to view your app locally on your computer via localhost, you can move to step 2.

Step 2: Find your Local IP Address

Open System Preferences > Network. Select “Wifi” in the left pane if it isn’t already selected.

Under “Status: Connected”, you should see “Wi-Fi is connected to and has the IP address < local IP address >.”

Take note of that IP address!

Note: It’s common for your Local IP Address to change automatically when your device or other devices connect/disconnect from the network. So you can’t really bookmark this address. Instead, you’ll have to find your address each time — for me, this is usually just when I get started each morning and it stays throughout the day.

Step 3: View on your phone

On your mobile device’s browser (any will work), navigate to http://:.

For example, if I was serving on localhost:8080 and my local IP address is 123.45.67.890, on my mobile device’s browser I would navigate to http://123.45.67.890:8080 . The http:// is important, don’t leave it off.

Success!

You should now be viewing your app on your mobile device. Set it up right next to your main monitor, because it will reload every time your localhost reloads, so it will be perfectly in sync with the locally served desktop web application.

You don’t get any front-end devtools with this experience, but you do get an early warning if things look or behave differently on a native browser’s experience.