a Newcomer Handbook for Software Developers

How to Optimize a Newcomer Handbook for Remote Software Developers

When you’re trying to hire a talented software developer, you have to make the job attractive for them. This is a rewarding profession with a projected growth of 25% from 2021 to 2031. That’s much faster than the average predictions for other occupations.

Companies face huge pressure to make the environment positive for newly hired developers. If we’re talking about remote workers or contractors, it’s even more difficult to make them feel like part of the company’s community. A great employee handbook can help them fit faster and better. It will include all important details about their position, so they will get the needed training without any need to be present in the offices.

The Importance of a Handbook in the Remote Developer Onboarding Process

Remote software developers and contractors as well as in-house tech team need to be informed about specific job details, such as the company’s general processes, tools, protocols, and guidelines for getting things done. You can learn more about the onboarding process in our previous blog post, but today we want to focus on the tutorials and handbooks that will make remote developers’ life easier.

Some companies provide a series of tutorials or electronic journals. We recommend assembling all that information in a handbook, which the engineer can access anytime in the future. It will be easier for them to navigate through a single handbook than to search for the right explainer video and wait for the right second that answers their question.

You’ll need to systematically update the handbook, so it will serve its long-term purpose.

There are several reasons why an employee handbook is important for the onboarding process:

  • It diminishes the chance for miscommunication between the company and the remote developer/contractor
  • The new hire gets a detailed overview of their position’s responsibilities
  • The handbook includes documentation standards, machine and software requirements, and other details that speed up the training process

10 Things to Include in a Handbook for Contract or Remote Software Developers

1. Details on the team’s values

Your handbook should start with a warm welcome note for the new contractor/developer. Mention how each member of the team is appreciated as an important part of the working process. Remote software developers will communicate with the team members on a daily basis. Although they don’t directly experience the office culture, adopting the values of the in-house team will make them feel like they are a part of something bigger. Instead of simple task completion, remote engineers will focus on creating better final solutions.

Team values are a motivation booster, which leads to more productive remote work.

This part of the handbook doesn’t have to be specifically adjusted for software developers. It’s easy to repurpose it throughout the onboarding materials for all other team members.

You can also include a short bio (with a photo) for the team members and supervisors that remote software developers are most likely to communicate with.

GitLab is a great example of a functional onboarding handbook. The first part (information about the company and its culture) is shared across multiple pages in the document.

GitLab valuesSource: GitLab

2. The developer’s role and responsibilities

How does the remote software developer fit into the organization’s values that you just shared with them? What responsibilities will they have in the department? Without any specified daily and long-term expectations, miscommunication can easily occur. Contractors want to perform well and complete all tasks on time, but they can’t read minds. The requirements have to be clear.

This section of the handbook should clarify several questions that the new hire has:

  • What’s the exact job description and what responsibilities come with it?
  • Are they expected to work during specific business hours or can they organize their own time?
  • Do they have to be online and responsive all the time, or can they work flexibly?
  • How will their performance be measured? Are they expected to use tools that track working hours and productivity?
  • Will they be required to attend training programs?
  • How and how frequently are they expected to communicate with the rest of the team?

Basically, this part should set the expectations for the software developer’s work and behavior.

3. Machine and software requirements

Remote software developers may use their own hardware to work from a home office. If their machine is outdated or they use an incompatible OS, you can expect inconveniences along the way.

The handbook should contain clear instructions on the expectations regarding devices. If the entire team uses macOS, newly hired remote developers will have to follow that requirement. The handbook should also include tips for coding on the OS your company uses. You’ll find great tips on solving macOS problems here. That’s a good example of how this section of your handbook should look like.

4. Source code repository instructions

When a new software developer enters the team, they are expected to fit into ongoing projects. They need access to the code repository, so they can see what the other developers have achieved so far.

The handbook is not a place to include the actual code repository. However, it should contain instructions on how they can access the code and what level of access they will have. You should also mention what repository hosting service your company uses, and how it detects the workflow.

5. Development tools in use

Remote software developers must be informed about all important tools and software the team uses. You might need to offer an actual training process to get them acquainted with the tools. However, the handbook should include a list of software they will need. There’s no need to get into details; just ask them to install those tools and try using them before the training session.

Ideally, you can attach detailed manuals on how to use the tools (separately from the handbook). That’s how the learning process can start before the first day on the job.

6. Standards and styles of coding

Each development team has its unique way of implementing coding practices. Coding style is a personal matter, and that’s why it’s such a challenge in a team setting. To avoid arguments about “messy” and “proper” code, organizations usually set up style guidelines for their developers to follow.

The handbook should include guidelines on how the team usually writes code. This step will help the new employee read and understand the source code, and it will help them conform to the required standard with their own contributions.

You can also include guidelines on pair programming sessions. Newly hired developers will work together with team members who are already trained. The handbook will clarify the tools that they will use for remote collaboration, and explain the benefits of a pair programming session.

7. Documentation standards

Software developers are responsible for documenting all stages of a project’s life cycle. Your organization must set documentation standards. The documents will explain the product’s functionality and prompt discussions on significant matters between developers and stakeholders.

Your team may use the waterfall approach for documentation or agile approach. No matter what your company’s documentation practices are, you should share them in the handbook.

8. Details on the deployment process

Most IT companies deploy software updates, so the new developers have to be informed about those processes. The handbook should include details on how the team manages the release, installation, tests, deployment, and performance monitoring of its software products.

The methods that your engineers use for building, testing, and deploying new code impact the product’s response to changing requirements and preferences from the customers. Does your company host applications on cloud services or on its on-premises IT infrastructure? What kind of workflows for fast and frequent deployment have your software developers created? Share your practices in the handbook, so the new team members will be informed before their first day on the job.

9. Support and issue management process

Various issues during the working process are inevitable. Who should developers contact? If they face particular problems with their work, should they contact the supervisor or directly go to the manager?

In addition to issues associated with their work, remote software developers may also face violations of the employment agreement, conflict of interest with any of the team members, sexual harassment, and other issues with the code of conduct. Who should they contact in that case?

The handbook should specify all communication channels for different situations. Does your team have daily video conference meetings? Do you send positive daily or weekly emails to maintain team spirit? Basecamp’s handbook has a good section that covers that point.

Basecamp handbook for employeesSource: Basecamp

10. Company sites and external sites important for the business

Finally, you can wrap up the handbook with a section with important links. The official link to your company’s site is the first one you need to share. You can also include links to important past and present projects, as well as collaborative businesses.

MobileJazz has such a section in its popular handbook. It’s a good example because the links come with a great explanation.

Final Thoughts

The company’s handbook for remote software engineers can boost the effectiveness of its onboarding process. It engages new developers, clarifies the working process, and tackles potential issues and solutions. A great handbook will make the developer confident that the company cares about its workforce. Contractors often miss such a connection, which leads to lowered productivity and miscommunication issues. 

The handbook should focus on making contractors feel as part of the in-house team, despite the fact that they work remotely. That’s the first step towards onboarding productive engineers, who identify with the brand’s culture.  

Most of all, it’s easier for the new team member to get as much information as possible in a single handbook than to get it spread across multiple email messages.

Written by
Anna Lysiuk

Anna Lysiuk is a part of the MacPaw marketing team. She likes to share knowledge about marketing trends and enjoys writing about employee management, as well as macOS innovations.

View all articles

Tell us about your plans on a brief intro call and we’ll start the matching process.

Hire developers