Custom code is a double-edged sword. On the one hand, custom software provides you solutions with exactly the functionality your organization needs. On the other hand, the custom code requires knowledgeable developers who can add features and update the existing code base.

Inevitably, that code will need to be passed from one developer to another. Whatever the reason, custom code presents a transitional challenge since it’s proprietary code that the new developer won’t be familiar with. Therefore, it’s essential that there be a clean handoff facilitated by clear and complete documentation.

Why Software Handovers Happen

The migration of the responsibility for the development and upkeep of an application happens for any number of reasons. These can include:

• Transferring responsibility between internal teams
• Onboarding a new developer
• Offboarding an existing team member
• Transferring development of custom code from a consultant to an in-house team
• Handing off an in-house application to a consultant or partner

Regardless of the reason for the handoff, the new developer or team will need to understand the application, including purpose, features, backlog, and history. Complete and well-organized documentation isn’t nice to have in these cases – it’s an absolute requirement.

This documentation comes in two types – a project level understanding, and deeper, more technical documentation that describes the architecture, code, deployment, and testing specifics.

Custom Code Knowledge Transfer

Project Knowledge Transfer

If you’re bringing on a new team or a new consulting partner, providing a project-level overview will prevent a lot of questions and missteps from occurring in the future. Knowledge transfer at the project level should include business purpose, background information, feature backlogs, and user support documents.

Project Backgrounder: What is the purpose of the software? What is the problem that it solves for the company? Does it interface with other applications? Your backgrounder will include any information that will complete the picture of the custom application. Include items like:

• Application history
• Project and application challenges
• Project management processes used: Waterfall, Agile, etc.
• Development mode: active or maintenance

User Documentation: User documentation is important for more than just support. Understanding the user’s perspective and how the application is described to the end-user can help the new team or developers gain key insights into its purpose and design.

Backlog/Parking Lot: What features have been asked for, but haven’t been started? How long have these been on the list? Understanding the backlog and the prioritization of these items will let the new project team in on what lies ahead.

Feature Status: Provide the new team or developers with a list of current features and their status. What’s “done”, what’s in development? This goes hand in hand with the backlog. Include priorities with these items, so the new developers understand what the most important functionality to work on next is. You should also include any required timing for the listed features.

Technical Knowledge Transfer

Whether handing off the custom code to a new consulting partner or onboarding a new team member, technical documentation is, of course, crucial. From high-level architectural documents to code repository structure and deployment instructions, technical documentation is where the rubber meets the road.

Architectural Documentation

The architectural decisions for your custom software are as important as the code itself. Internal developers will need to follow the established standards so that their code will interface cleanly with any other internally built applications. Software consultants will need to understand your architecture and guidelines to make any handoffs back and forth as smooth as possible.

Your architectural documentation should include:

• System and software architecture designs
• Established coding standards
• Secure coding expectations
• Software interface standards for integration to other systems
• Environmental structure (dev, testing, production)
• Current architectural risks
• Database structure
• CI/CD standards, if applicable

Coding and Testing Documentation

The nuts and bolts of your custom software should be outlined in the documentation included alongside the code itself. These documents should cover everything that your coders and QA resources would need to understand code structure, data, classes, automated and unit tests, and deployment.

Your documentation should include a few key elements to make the handoff go more smoothly:

• Description of important classes and application layers: This prevents the new developers from needing to search for locations where changes should be made.
• Integration maps/WSDLs/interfaces: What integrations are important, and how are they implemented?
• Manual processes: Are there current processes that must be completed manually? What are those, and who are they for?
• Requirements: Are there required packages that must be installed when setting up the environment?
• Staff, roles, and responsibilities: Define for the team who the users that will need access to the system are and what their privileges are.
• Access and Logins: Detail any specialized access instructions, as well as standard logins that are needed for that access. For instance, is there a database account that is used for the connections? What is that, and how is it used?
• Software licenses: If there are 3rd party components used as part of the solution, those should be listed including their usage, terms, and keys.
• Issue submission and resolution: Where and how are issues recorded and tracked?
• Common and recurring tasks: Describe any cron jobs or scheduled tasks associated with the project and that need to be executed frequently. Documentation should include how these tasks are logged and if and how error alerting is handled.
• Backups: Document the components and data in the systems that need to be backed up and at what frequency. Where do they get backed up to, how frequently, and how long are they stored?
• Monitoring: Beyond scheduled tasks, what other monitoring exists? How are processes monitored and issues handled? Who receives notifications, and what is the process for prioritizing outage issues?
• Maintenance Plan: If there are upgrade procedures in place, provide those to the new team or developer. This allows work and testing to be scheduled around and in tandem with the appropriate updates.
• Version control instructions/procedures: Source and version control should be maintained regardless of the developer. Understanding the procedures will also help the team find previous code branches that may become relevant later on.
• Known bugs: In addition to a known bugs list, include any common debugging or troubleshooting steps.
• Deployment guidelines: What are the steps for deployment? Think beyond just code deployment and include any information about database updates or refreshes, admin credentials, and so forth.
• QA documentation: Are their automated tests already written? Test scripts? How and where is testing done? What level of unit testing are the developers responsible for?

Handing over customer software is not a task that can be done quickly. It requires comprehensive documentation and the time to review the code, features and functionality, and other elements associated with the application. When doing a full project handoff, you should plan for at least a month for the transition, including two weeks for documentation and training and the remaining time for the active transition with the original developer or team available to help, answer questions, pair program, or support the handoff.