Main author: Noemi Kowalewska
Other authors: Tomasz Klemens, Bartosz Mocek, Michał Masłowski
Introduction
Carrying out a project handover sounds very easy in theory; after weeks or months, or even years, of developing an application, you just transfer it from one team to another.
When done correctly, it might be very simple and quick. But sometimes it is not.
How do you manage the entire process so that it benefits both parties?
Let’s take a look at it together and read the interview with our team members who took part in a recent project handover and hear their very interesting reflections on this topic.
Could you tell us a little bit more about how you approached the application handover process?
First, we sat down and thought about the handover plan. We created workshop points that we would discuss and passed them on to the client. Our client then created a list of the things he wanted to know.
Based on these two lists, we prepared a meeting plan and our steps to prepare the points listed in them.
We divided the workshop into 1.5-hour blocks, with a presentation part and question time.
During the workshop, we discussed the technologies we used and our how-to pages. The order of workshops was arranged in a top-bottom fashion whereby we started with a general overview and then went into details. We realized that there were some topics that we wanted to explore more thoroughly, so we made the decision to extend our plan.
What practices should you follow to make it successful?
It’s important to have meetings with the team to answer their questions and concerns.
It is also worth maintaining the code according to good practices throughout the life of the project, using linters, and documenting the code.
When something is not obvious, it is worth adding comments. We should always treat our code as if we were to pass it on to someone else. We should always remember about testing as well-tested code is a lot easier to understand.
Is there any stage or practice that is most important for everything to go smoothly and successfully?
Documentation is important, but a developer really only starts learning when they sit down and start coding. The best way to learn about the project is via pair programming as programmers can see the code and think about potential problems they might face during implementation.
What were the main challenges?
The first main challenge is trying to understand how many details may not be known by the team that sees the repository for the first time, and how much knowledge is needed to enter an existing project.
What is more, support for exotic operating systems. It is worth knowing what systems the customer’s developers are using. It may turn out that all the programmers on our side work on Linux and the client’s developers have Macs, so there may be development problems that no one predicted.
We also didn’t know what programming level and knowledge about AWS our client’s developers had. We are an AWS partner and we use a lot of technologies and services from AWS, even not so popular ones. We had to ask them questions to make sure that we were on the same page.
Creating live coding examples for the most complex parts of the system was also a challenge.
What mistakes should the development team avoid during the handover?
We think that they should review all important functionalities to provide knowledge on how to extend them or add similar ones. There was one situation where we forgot to explain a certain feature to our client’s team and then later realized, by looking at their pull requests (PRs), that we needed to explain everything to them in detail.
What about documentation?
It is very important to have high-level architecture documentation and defined processes that outline the communication between services. It is also very important to write how to configure this communication and explain somewhere in the documentation the process of deploying the application to production and developing new features.
How has going through the handover process changed your point of view of software development?
Documentation is usually created to show the client what we have created for them. We forget that it is there for us (developers) to help maintain the project.
When creating a functionality, it is very difficult to keep an eye on the current documentation, even the high-level changes. It is worth creating and maintaining documentation, despite the fact that it is difficult to do so.
It is also important to create abstractions in the code where there are complicated functionalities. When explaining the code, we do not have to go into unnecessary details.
A Handover Checklist
- Send the client a list of services and technologies used in the project to assess their knowledge of them.
- Create a workshop plan with the client’s development team.
- Review your documentation, check if something is missing, and update it.
- High-level docs
- README
- Deployment process
- Communication between services
- Environment variables
- Create instructions to develop features which are complicated and influence other parts of the systems.
- Meet with the development team and explain the purpose of the project, architecture, and code.
- Encourage the client’s development team to make some changes. Learn how to make PRs and communicate through comments. Review the client’s PRs and help them to create new features via pair programming.
