This article covers the basics of onboarding with a new client as a software engineer contractor. We will look at the people, resources and dynamics involved in successful onboarding with thoughts to reference as you onboard.

Why You Are There

There are many reasons why contractor roles exist. Most of the time you are there to solve a problem for the client, provide temporary staff augmentation or to be an added resource on a specific project. These are all happy reasons why a client would take on a contractor.

Conversely, there are situations which are not so happy in their origin, due to issues within the client organization, unsuccessful projects, people leaving unexpectedly, or poor performance of “the last contractor we had …”.

Whether the situation is happy or not, you have to carefully navigate, listen, watch, take notes and balance your initiative with diplomacy.

If you are introverted by nature, take deliberate action to build communication with your client. (more on this in Personality Matters below)

Who’s Who

Notice that we did not begin with “What’s What”.

Identifying the key players within your client organization is crucial, because you need to build relationships for everything else that follows.

• Make a list of leadership, management, team leads, people with specific skills.
• Understand their business model, answer the question “what does your client do?”
• Start watching their work styles, schedules and how they communicate. This will help you get in sync with them for vital collaboration.
• Client Log for capturing Who’s Who info. (see Dev Log below, I do the same thing for Client info)

Get Set Up

This is about getting set up to work, with repos, credentials, access(“…add me to this or that”), slack channels, documentation and tribal knowledge. Obviously you can’t work if these things are not in place, but remember there is no perfect onboarding (if “perfect” means that you have everything needed, in the first hour of day one).

Why?

• To crank out code and ‘billable hours’ as soon as possible.
• To be ready to set up a new machine if needed.
• To be ready to help onboard a colleague on the same project (the client will expect you to have retained any knowledge transferred).

Client teams are often deep into their code base for many months or years. It is difficult for them to see the project from a new person’s eyes. Capturing the details of setup is a valuable contribution to your client.

• Read the README, follow all links to info, record issues accessing the Client’s existing documentation and processes.
• Keep track of the things that were required for being fully set up and ready-to-work.
  • It will help you and your company to capture this information.
  • It will show your client that you are efficient and listening.
  • Embrace the unfamiliar, record your adventures
    • This helps you prepare solid questions
    • This helps you rubber duck opens a new window your questions, often solving them on your own

Onboarding a new contractor helps reveal gaps in client documentation and processes. The more you can roll with it and keep working positively, the better. Nobody has complete documentation of the app, environment, business logic, you-name-it. You will have to ask for things, repeatedly, diplomatically (and without complaining or making a client feel stupid that they overlooked it).

1) The bad news: There is no documentation. Be cool.
2) The good news: There is documentation, but it is outdated. Stay cool.

Be aware of client team dynamics. They might be stressed for many reasons. They might have had very little help when they started working there. You might be coming in to do something they were not able to do (and they might either resent you or fear you, just because of your role). Stay calm and present your requests as friendly and non-threatening as possible. Edify others, communicate, show respect and be humble.

Quick Wins

The idea here is to get a positive result for your client as soon as possible. Obvious, right? This does not have to be a major release game-changing pull request. It is human nature to seek to be “understood”. As an outsider coming into an organization, the one thing you can do is show respect and acknowledge others genuinely.

• Sincerely try to understand what people are saying and their feelings.
• If you “get” me, I automatically “like” you and tend to see you as competent.
• Help the Universe by understanding your fellow human beings.
• Give others a break, and you’ll get one, too.

This enables frank communication and collaboration. It translates into a perception of competence, giving you the benefit of the doubt early on, but only if you are sincere in your efforts to understand others.

Small wins that build the relationship:

• Build communication with key players.
  • Get curious about them and their work.
  • Ask about THEM, focus on THEM, talk about THEIR problems first.
• Show that you are listening, through the questions you ask.
  • Elaborate on the things they are talking about.
  • Ask them follow-up questions about the things they care about.
• Be willing to show your ignorance
  • Get clarity on resources, application flow, business rules, known issues.
  • If you missed something they said, show them respect by revealing your ignorance.
  • Have a sincere desire to understand what they want.

Notice that the quick wins start with the people first. Know where you stand with the client team. It is not enough to just code a solution.

Communicate reliably, even if you don't have perfect news.
Don't make your client chase you for updates and status.

The Tidy Question

This is about creating a solid question to ask a more experienced developer. Following the debugging points below will help you:

• Get clarity before you ask for time from another developer.
• Stay focused on the errors and steps you’ve taken.
• Be ready to get effective help when the opportunity arises.

Most experienced people are happy to help you, especially if they can see you’ve tried.

Debugging Points

When things are broken and I’m stuck, I use this five step process to get unstuck:

1) Goal: My goal is ___

2) Errors: The error I get is ____

3) Tried: I have tried to ____

4) Positives: Positives are ___

5) Solution: The solution was ____

1- Goal:

I am trying to “get data from this endpoint”

2- Errors:

An error occurred while installing libv8 (3.16.14.19), and Bundler cannot continue.
Make sure that `gem install libv8 -v '3.16.14.19' --source 'http://rubygems.org/'` succeeds before
bundling.

Something is preventing me from running Ruby 2.3.7 on Mac OS Catalina

3- Tried:

Uninstalled Ruby 2.3.7; ran brew doctor; manually removed openssl version 1.1 and reinstalled via Homebrew; didn't work;

4- Positives:

The front end client app is almost working.
I was able to access the repo today.
The database is running in the API and not showing errors
I can reach data from the Rails console in the API

5- Solutions:

Turns out that OpenSSL 1.1 was getting installed by Brew automatically.
I used MacPorts to install version 1.0, which ruby 2.3.7 requires
This allowed bundle to complete without errors

Fail Loudly

Seems counter-intuitive, right?

It can actually help reveal issues in the app, spark conversations to clarify things and often helps the client team get clarity on goals with their end users. This does NOT mean that you delete the production database. It might mean that you forge a working solution even if it is not elegant. You might do this just to prove a concept works, and to get feedback on how the client team would normally approach it.

There is an old saying: “you can’t steer a parked car”. I would much rather go into a stand up meeting with something that works, even if it is ugly, or something that is sensible based on my understanding.

If you can show your present understanding, more experienced developers can guide and correct that understanding.

Personality Matters

Programmers are often introverted. Sometimes we need to adapt our communication style to help another person communicate with us. Take actions that get you out of your shell so you can communicate in meetings. It is ok to “adapt” your communication deliberately.

Before a meeting, create talking points for yourself such as:

• Questions you need to ask
• Statements you want to convey
• Issues to avoid (know when to shut up)
• Relationship goals, such as:
  • I want to reassure James that I understand his issue
  • I want to praise Tina for her efforts on XYZ
  • I want to ask certain questions without undermining Carol’s strategy

The bullet points enable you to:

• Quickly summarize things
• Remember the essence of your point, allowing verbal improvisation
• Keep grounded if you are shy about public speaking

Watch for your openings in meetings. Sometimes an agenda is set in the beginning, where you can speak up and let others know that you have points you want to cover.

Dev Log

Form the habit of a daily developer log. Make it simple enough that you use it without thinking too much. I use Microsoft OneNote opens a new window simply because it syncs so flawlessly on all my devices. I create two-column tables, living in logical pages and sections in OneNote.

The two column table allows me the most freedom to capture my development day, error messages, events, scripts, etc. I don’t try to get too fancy with it, just a date in the left column and brain dump in the right column. Then any rows under that are associated to that date.

I also try to keep separate logs for:

• Setup Log
  • to setup an entirely new machine if needed
  • environment variables
  • scripts
  • urls to dev, test, staging, production
• Issues and Solutions Log
  • major blockers go here
  • everyday errors go in the dev log
  • anything that would block a new dev onboarding goes here
• Client Log
  • about, business model, what they do
  • who’s who
  • who can answer what
  • instructions to access the building, or acct info, etc.

Conclusion

• Put people first, “seek first to understand” your client and their business.
• Record your setups, be cool if things are not 100% day one.
• Maintain logs for dev, client, setup, issues.
• Create thought points and speak up in meetings.
• Ask tidy questions of experienced devs.