Code Documentation: How To Create Effective Handover Documentation
Get our development team’s tips for documenting and completing a software handover involving custom code.
Custom code refers to code which is specially tailored, or customized. This could be code linking two applications or systems, or code used for a proprietary software application. Since custom code modifies a standard code base, it is not universal to all developers.
Software Handovers
During some development projects, there are times when code needs to be transferred from one person to the next. A knowledge transfer for software may occur when:
- Someone new joins the team
- A developer transitions off one project to work on another
- Someone leaves the organization
- A project is transferred from one agency to another (rare instances)
In any of these scenarios, the developer working on the project needs to complete a software handover and pass along their custom code base to the new developer. While this sounds straightforward, if working with a custom code base it becomes more complex and it’s essential to create thorough and organized documentation.
How To Transfer Code (& Knowledge) Effectively
A standard part of any handoff from one developer to another includes documenting details about the code base they created. These details provide context, insight into how the code was written, and other important details.
Handover Documentation: What To Capture
Documentation is hugely important when it comes to transferring knowledge and code base. Code handover documentation usually includes three distinct sections, targeted at various audiences interacting with a project.
User Support: Documents written for any non-devs who interact with users of the app. This is typically troubleshooting steps that the CSR can take before escalating it to whoever the new devs are.
QA Workflow: Documents meant for anyone who can QA the app before an official release occurs.
Technical Documents: Super technical documents intended for other developers only. These developer-to-developer documents are what this post focuses on.
There are some key things to capture when creating technical documentation:
- System Architecture
- Code Base Organization
- Source Code Commits
- Database Schemas
- Source/Version Control Procedures
- Key Source Code Sections
- Coding Standards
Code Documentation: 6 Things To Include
Beyond the categories listed above, there are some specific details we recommend including in any code documentation endeavor. The list below can be thought of as a software knowledge transfer checklist to run through when determining what to include.
- “_Deprecated” Folder: Include a folder or a section in your notes with historical information, so it’s not lost in the event it’s needed in the future.
- Simple Steps: Include instructions with very simple steps on how exactly to push a new release of the code.
- High-Level View: Provide an architecture overview document with a high-level view of the application.
- Risks: Provide Current Risks with Architecture document. This is extremely important so the new dev doesn’t inadvertently make a catastrophic mistake that can occur with the setup.
- Manual Processes: Include steps for anything that is a manual process, such as pulling reports
- Bugs: Include a dev-specific set of documents for troubleshooting common or known bugs.
When planning for a handover of software, a month is an ideal timeframe to allow for the transition. The first two weeks can be spent on training and writing documentations, and the second two weeks can be spent in transition with the initial developer available for any questions or support.
Legacy software is an asset, but only if you know how to leverage it.
>> Download our free CodePath Assessment e-book for evaluating the health of legacy software assets so you can innovate risk-free.