Professional Courtesy Regarding Knowledge Transfer From Outsource Teams

10 November 2020

Photo: Unsplash - Elias Schupmann

I have looked at a lot of projects over the last year for clients of all sizes at Platform Eight. One of the trends I have seen in a lot of the projects is the failure to provide adequate handover documentation from outsourced teams. In some cases, there has been none.

This is not acceptable. When a business outsources development work they are entrusting the outsource team to deliver in a professional, timely manner. They are buying the expertise offered by the outsource team and have every right to expect the work to be completed to an acceptable level. This is why they are happy to pay outsource team rates. Outsource teams do project work as a matter of course. The expectation should be that they will not build an ongoing relationship with the business and therefore, they should hand over each project like that is the end of the partnership. A full knowledge transfer should be completed.

On more than one occasion I have taken on a project and found at least one of the following problems:

• The wrong repositories have been shared with the client.

• The right repository is shared but there is no README to provide a summarized view of how to get the project running locally.

• The commit history is full of one-word commit messages that provide no context or reason for a change or addition.

• There has been no handover of updated project assets, plans or documentation.

• There is no deployment documentation explaining the “where” and “why” around how one or more services is deployed.

This has to stop. There is already a distrust of technology teams and consultants and getting the simple stuff wrong is just amateur.

README Files

Each code repository should include a README file in the root of the project. The quality of the README can be a good indicator of the quality of the project. The aim of the file is to explain the project, provide an overview of how it is built and how to run it.

Like almost everything else these days, there are a lot of articles and guides on how to write a good README. For me, I would suggest that a README file should allow a new developer on the project to:

• Understand the aim of the project through a descriptive summary.
• Understand how to clone the project and install the required dependencies.
• Understand how to set up the project to run locally.
• Understand if any related projects are needed and the dependencies between the projects.

For open source projects, having the developer contacts and licence information is also required. Maintenance of the README file is important to ensure it stays relevant. This should be part of your code review process. Overly long README files that are not maintained or which are hard to read provide little value.

Given that most cloud-based Git services will generate a README when you set up a project there is no excuse to not have one. Or worse, have a blank one. If you need help or inspiration in creating a README then the following links might be of use:

• Make A Readme
• Awesome README

Commit Messages

When code is being developed, the changes will be added to Git source control. There is an acceptable standard for the messages that should be added to each commit. Again, I instil a standard that I expect from each outsource team at the start of a project. While developers may argue that it takes time to write meaningful commit messages, I disagree. When the developer writes the message the work is fresh in their mind. They have the opportunity to share the change, the context and the reasons they have made the changes they have. This again builds up into valuable knowledge that may not be captured elsewhere.

Knowledge Transfer

Knowledge is power and in the case of the technology powering a business, the difference between success and failure. If you opt to outsource some technical development then you must have a defined outcome and and expected set of assets that you must be provided. Be clear on these when you start the project and enforce receipt of them on completion. As a minimum I would expect:

• Access to all code repositories. You need to ensure you have access to all code repository’s that were created or used in the project. All code branches should be pushed to whichever cloud service that was used as origin. Each repository should have a README and all code and deployment related assets.
• A deployment plan. A top-level diagram of the deployment of the application plus a detailed document covering the underlying services used and their configuration. This should also detail how to set up the deployment from scratch, any external services used for monitoring or error tracing and details of the database (schema, security and roles etc).
• Credentials & Secrets. Ideally, you will set up a centralised password and secret tool to share and keep passwords, API keys and third party service access routes.
• Design Assets. All design work and generated assets such as image files and videos.
• Sprint data. You should be using a work planning tool such as Jira or Trello to log the agreed work. Once the project is over you should retain access or have that data exported so no knowledge is lost.
• Full IP Ownership. Once the project is completed then you should have a document confirming that all IP is transferred to you. This usually is included in the contract. However, I have worked on projects where the outsource team have used in-house developed libraries or systems and you should insist that you retain ownership of this code. If that is not possible then you need to decide on how to proceed but I would recommend at the very least that you agree on a maintenance & licencing basis to ensure you receive all future updates

None of the above assets should be chargeable by an outsource team as they are part and parcel of every professional software project. They are core elements that all projects should contain to ensure that knowledge can be transferred between developers and teams regardless of if they are in-house or outsourced.

I make a point at the start of each relationship with an outsource team to ensure that they know what my expectations are regarding a handover at the end of the project. For non-technical founders and startups that entrust outsource teams, they do not know what to expect upon delivery as in many cases this might be their first time running a technical partnership. Don’t be the team that fails to provide a full handover, do the right thing and raise the standard.

If you have any thoughts or comments about this subject then let me know via twitter or email.