How to Avoid Handover Nightmares

A handover is the process of migrating resources and responsibility of a project from one team to another. It is one of the critical stages of any software development cycle. The way this process is carried out affects the project outcomes and therefore should be well planned and executed.Being software engineers, we spend most of our time working with different teams and projects. This means that we have to go through an onboarding process to get us up to speed. At times this process can be a bit overwhelming and frustrating, especially if key elements are not tackled to pave the way for a smooth, clean migration.Such elements include:

• Documentation of the project and infrastructure.
• Accounts and services used in the project.
• Product policies and guidelines, etc.

Because engineers spend most of our time concentrating on building new features and enhancing products, we often completely ignore the possibility of handover at a later time. This eventually leads to handover nightmares that no one would like to go through.I’ve been thinking about handovers a lot lately, as I recently managed a handover in my role as a DevOps engineer. My goal was to facilitate the handover process to ensure a smooth transition with minimal downtime. Along the way, we faced a few challenges that I felt could have been avoided if handover had been considered from the early stages of the project.Today, I am going to share with some of the things I learned during this particular handover process, and how they should be handled during the initial stages of development to avoid transition inconveniences.

Keep things simple.

Software architecture can grow complex as a product scales. It is sometimes impossible to avoid this, but as engineers, our goal should always be to simplify the project as much as possible.

“Making the simple complicated is commonplace; making the complicated simple, awesomely simple, that’s creativity.” — Charles Mingus

Do not over-engineer your product. If your project is growing, consider breaking it up into smaller components that you can easily manage. You can also consider leveraging preexisting services or API to build your product rather than reinventing the wheel.Here’s a good example: If you are working with video calls, you can implement your own service, which comes with hosting and cost implications. Or, you can consider using Twilio or Google Hangouts, saving tons of code, time, money, and frustrations — and at the same time benefiting from a well-tested, quality service. The latter option makes much more sense.

Document everything.

Documentation is very important in software development. A well-documented project is easier to understand and maintain.

It is very easy for someone to get lost in a large codebase if it’s not well documented. Do not assume that everybody knows what you were thinking. I myself sometimes get lost in my own codebase. Documenting it or using self-explained variables and function names makes it easier for me to debug and navigate the codebase with ease.

“Lack of documentation is becoming a problem for acceptance”. — Wietse Venema

Working with an undocumented codebase is like someone throwing you into an ocean with a raft with no compass and expecting you to get on shore in a set amount of time. To avoid this situation, make sure that every inch of your codebase is documented and straight to the point.If you are using any additional services, it is also wise to include this in your documentation. This will allow the team taking over the project to be aware of any dependencies and cater for them when making any changes.

Adopt workflow and best practices.

In almost all languages and frameworks, there are recommended workflows and best practices. These workflows are designed to provide a common approach to using certain technologies for efficiency reasons, but mostly for maintainability.

Adopting community-recommended workflows makes it easier for other developers to navigate through your codebase and get up to speed as compared with using your own approach. I am not saying that you should never be creative and come up with your own workflows: At times a project might demand improvisation. But even if this is the case, it’s essential to ensure that your workflow is consistent and well documented.The key thing here is having a set of rules that should be followed from development to deployment. This not only guarantees quality but also makes it easy to work in teams.Another reason to use best practices is to ensure that quality code is being shipped to production and can be easily changed without causing a lot of downtime.

Employ separation of concerns.

In computer science, separation of concerns (SOC) is a design principle for separating a computer program into distinct sections, such that each section addresses a separate concern.

When building applications, this is one of the things you incorporate into your workflow. Using this approach will enable you to distribute tasks across teams with minimal conflict, making it easy to manage complex apps.A good example of separation of concerns is in microservices, where you break down monolithic apps into small, independent units that can work together as a fully functional app. If you are using Python, Django apps are another way of applying this principle.Separation of concerns can also be used in building infrastructure for hosting applications. In this context, it is advised to separate the production account from the development account. This provides an easy way of managing both environments but also eradicates the possibility of polluting your production environment.

Avoid using personal accounts or credentials.

Continuous integration is one thing we cannot go without these days, especially if you are a DevOps Engineer: Tinkering with various tools for monitoring, logging, deployments, testing, and so forth is like a religion to us. However, the use of these tools can lead to having multiple accounts, especially when using a service that cannot be self-hosted.To avoid this situation, most of the time we tend to use one account across multiple projects. In some instances, this is a good idea since you will have a consolidated dashboard for easy management; however, when it comes to handing over these projects, it doesn’t work so well.Some services, like Heroku, provide account transfers. For others, this is not the case. Therefore, you will have to create other accounts and change configuration across all related services, which can be painful and frustrating.To avoid this kind of situation, I recommend having isolated accounts for each project you are working on. Responsibility for managing individual accounts should be handed over to team leads or technical officers, and credentials stored in vaults (e.g., LastPass) which will make handover as simple as sharing the folder with credentials.

Automate as much as you can.

Modern-day software makes use of different services, and this complex infrastructure can be hard to maintain manually. A good example here is AWS. AWS has a lot of services that can be used to build software. Provisioning all the services can be done manually. However, in the event of failure or corruption of the infrastructure, it can be hard to replicate the same environment, thus leading to downtime.AWS has come up with awesome tools to make provisioning services through the use of configuration approach e.g CloudFormation. The community, on the other hand, has also built tools that are built on this service making it easier to version infrastructure and rollback easily. With infrastructure as code, maintaining the production, dev, or staging environments can be done by just running scripts and commands.Here are some of the tools that you can use to get you started:

• Ansible
• SparkleFormation
• Terraform
• Chef
• Puppet

But I will have to warn you: Once you take the automation path, there is no turning back.And last but not least:

Write good code.

I sometimes tell my colleagues that code is like poetry and should be written as if you are wooing the computer. It should be expressive, well indented, and easy to read.

“Write code as if the next person reading it is a psychopath and he knows where you live.” — Unknown

This is just an overview of some of things you can do to make handovers easy for you and your team. The key point here is to ensure that you are considerate on how you design your applications to pave the way for seamless handovers.(If you like this article, comment, like it, or share it with the world!)