Managing technical debt in template development

This article shares details on how Robin De Clercq (Business Solutions Tech Lead) and Michiel Degezelle (Business Solutions Solution Analyst Developer) started identifying and managing technical debt in the Silverfin Business Solutions (BSO) team’s codebase.

The BSO team operates as a product team and specialises in building and managing solutions (i.e. templates) on the Silverfin platform, using the Silverfin Templating Language (STL). STL incorporates Liquid, along with a bit of HTML and CSS. Silverfin Liquid is a derivative of Shopify Liquid, which is an open-source template programming language created by Shopify and designed to be highly accessible and user-friendly. The Liquid templating language used at Silverfin relies on all core functionalities of Shopify Liquid, but includes significant customisation to cover the Silverfin use-cases.

The Liquid codebase has grown exponentially over the years. Along the way, questionable design choices have been made, certain practices have been replaced by better practices and the Liquid language itself evolved as a templating/coding language. As a result, the template codebase is very susceptible to technical debt. Our increasing cycle times, higher bug resolution times and large refactoring projects are a testament to this.

With the help of the Silverfin backend engineers, the BSO team has started creating awareness around, documenting, quantifying, and planning technical debt. The article below delves into the details and lessons we gathered during this process.

Technical debt

Robin De Clercq - Solution Technology Lead

Technical debt (TD) is a metaphor used by the software community to describe technical decisions that can give companies a benefit in the short term but possibly hurt the overall quality of the software and the productivity of the development team in the long term ([1] and [2]).

It is a hot topic in the software developer community. Organisations worldwide are piling up technical debt and even the biggest organisations sometimes struggle to manage the debt in their codebase [3].

Even though ‘debt’ has a somewhat negative connotation, injecting tech debt intentionally during software development is a common practice for software teams because it can help to achieve the project’s goals sooner or more cheaply [4].

Managing technical debt should not only be a developer’s concern. Time spent on handling technical debt in a codebase directly impacts the time a development team can spend on new feature development. Technical debt is estimated to waste up to 42% of developers' time (or an average productivity loss of 40% [5]) and has a direct impact on developers' wellbeing and motivation. Moreover, during a study conducted in 2022 by Cornell University, it was demonstrated that low-quality code contains 15 times more defects than high-quality code. Furthermore, resolving issues in low-quality code takes on average 124% more time compared to resolving bugs and issues in high-quality code. That same research indicated that low-quality codebases experience a decrease in velocity and a maximum cycle time that is nine times longer.[6].

Technical debt in templates

Robin De Clercq - Solution Technology Lead

When I joined Silverfin, the company was scaling significantly. This rapid growth meant that we were developing our product at an intense speed, often writing thousands of lines of code each day. At that stage, our primary focus was on meeting deadlines and delivering features rather than long-term code maintenance. This approach is justified, as taking on technical debt is not necessarily bad. However, as our team, product, and codebase expanded, and as we matured as software developers, it became increasingly clear that managing technical debt in our templating layer has become essential.

Before we can address technical debt, we first need a shared understanding of what it means in the context of (Silverfin) templates. Technical debt can take different forms [7], and in our project, we identified two main categories:

1. Technical debt in the Silverfin Templating Language
2. Technical debt in code architecture

Managing technical debt

With the support of our engineering team, we implemented a structured four-step plan to manage technical debt more effectively. Our approach emphasises close collaboration between business and development teams to ensure technical debt is addressed and prioritised in a way that aligns both the product and business goals.

1. Creating awareness around technical debt

Robin De Clercq - Solution Technology Lead

The first step involves defining technical debt clearly to ensure alignment across teams and projects. This includes formalising definitions, clarifying misconceptions, and establishing best practices for monitoring and measuring technical debt.

To foster a shared understanding of technical debt, we hosted a series of sessions on the topic. The goal of these sessions was to go beyond developer teams and establish organisational awareness, which is why we involved our Product teams early in the conversation. A questionnaire conducted within the BSO team revealed that 76% of respondents expressed growing concerns about technical debt and the lack of organisational awareness regarding its impact. This reinforced the need for a structured approach to address the issue at all levels.

During these sessions, we focused on the business impact of technical debt within our codebase. To quantify its effects, we started measuring key metrics more closely such as:

• Pull request cycle time: measuring how long it takes for code changes to be reviewed and merged.
• Bug resolution time: assessing how quickly issues in the codebase are identified and resolved.
• Refactoring efforts: tracking past refactoring projects and the time invested in managing code complexity over the years.

By clearly demonstrating the trade-off between time spent on new development and time required to manage code complexity and debt, we were able to highlight the long-term implications of unresolved technical debt.

These discussions made technical debt a common topic of discussion and a shared responsibility, ensuring that new templates and workflows are designed with a stronger focus on maintainability.

2. Documenting technical debt in templates

Michiel Degezelle - Solution Analyst Developer

Clearly documenting and visualising existing tech debt in the Silverfin Liquid codebase provides a clear overview of where technical debt exists and helps stakeholders understand its impact.

Technical debt in Silverfin Templating Language (STL)

Since STL is a heavily customised language, we applied a broader definition of technical debt:

• The tools and framework evolved over time;
• Coding practices that were considered best practices five years ago are no longer maintained today;
• Additionally, the templating language itself contains outdated syntax —including drops, attributes, or methods— that are no longer supported but still present in the codebase. 

These elements impact the readability, maintainability, and adaptability of our code, making it a key source of technical debt.

This approach resulted in a limited list of deprecated Liquid tags and outdated coding practices. We systematically tracked each identified element and recorded them across the relevant repositories. To measure the full impact of the technical debt, we assigned a weight to each item on the list. For this we applied a very similar approach as the one described in an article of Riot Games [8] (further referenced as ‘measurement taxonomy’).

This approach considers three dimensions:

• Impact: evaluates the likelihood of technical debt resulting in user-facing bugs or issues.
• Fix cost: assesses the complexity for developers to fix or work around the debt.
• Contagion: estimates the potential for technical debt to spread in the codebase if left unaddressed.

By applying this measurement taxonomy, we could achieve a more nuanced understanding of technical debt, which is valuable for future strategic decision making.

Technical debt in code architecture

Beyond language-specific technical debt, we also took into account architectural debt within our templates and workflows. 

Compared to technical debt in STL, technical debt in code architecture is harder to objectively and systematically document. After all, if you discuss this topic with original authors of the templates or more experienced template developers compared to new team members, the conclusion might be different. 

For measuring technical debt in our code architecture we used a structured questionnaire that focused on different aspects of technical debt. This unlike the STL analysis, which was solely quantitative:

• Dependency on key personnel: examine reliance on specific individuals or roles.
• Readability and maintainability: assess usage of coding principles.
• Usage of shared parts: evaluate how much the code could be improved by introducing reusable components, which are similar to functions in most programming languages but are referred to as ‘shared parts’ in STL.
• Functional dataflow: evaluate the logical flow of data from a functional standpoint, ensuring that the flow is clear, efficient, and easy to follow. 
• Lack of documentation: determine the availability of essential documentation, including guidelines and design documents. 
• Test coverage: assess the range of testing scenarios. 

3. Quantifying technical debt in templates

Michiel Degezelle - Solution Analyst Developer

While it’s crucial to first identify and document technical debt, targeting and planning for its resolution is equally important to ensure we address the right issues in a strategic manner. In this phase, we assess, categorise and quantify technical debt to determine which areas should be dealt with first. 

The main goal of this step is to help stakeholders —such as the product team and scrum masters— understand the expected resolution times. This allows them to prioritize tasks more effectively.

Technical debt in Silverfin Templating Language (STL)

To give a sensible estimate to resolve technical debt in STL, we used the fix cost from the measurement taxonomy described above. These time estimates cover not only the development time needed to fix the debt, but also the associated review time (both code and functional) and time to write additional tests.

Technical debt in code architecture

As in the documentation phase, the subjectivity and lack of standardised solutions for many issues means that our estimates in this category need to be flexible and context-dependent. We have grouped the different aspects of technical debt in code architecture into three sections, each with its own method of quantification and estimation.

1. Readability and maintainability / Usage of shared parts / Functional dataflow / Dependency on key personnel

In order to resolve these aspects of technical debt a proper refactoring project should be introduced. We decided to use historical data (number of days spent on refactoring for other similar projects) as a benchmark. This provides a rough estimate of the effort required for each respective workflow, giving us a comparative baseline for planning.

2. Test coverage

To estimate the effort to increase the test coverage, we rely on both the results from the questionnaires and test coverage metrics.

3. Lack of documentation

Documentation efforts are assessed using the questionnaire responses to evaluate the current state of documentation. 

4. Resolving technical debt

Robin De Clercq - Solution Technology Lead

As a final step in our four-step plan to manage technical debt, i.e. executing the repayment plan we again actively involved our Product teams. As stated above, one of the main goals of this project was to create organisation awareness. It was therefore important to detail and hand over the insights we gathered around the state of technical debt and resource allocation to resolve the technical debt in our codebase (as described in 2. Documenting technical debt in templates and 3. Quantifying technical debt in templates).

By combining our findings with upcoming feature development plans, Product teams are able to strategically prioritise refactoring efforts. For example, if we know we want to add a lot of new features to a certain workflow in 2026, it makes sense to focus on refactoring, documentation and testing for that specific workflow during the current year in order to create a solid foundation for future development.

Finally, thanks to our effort in creating this awareness throughout the organization, individual development teams have set team objectives around (resolving) technical debt.

Follow-up

Since managing technical debt is not a one-time effort but a continuous process, we plan to iterate over our four-step methodology going forward. On a yearly basis we want to re-evaluate our documentation on the state of technical debt in our codebase, and update the estimates to resolve this debt. In order to maintain large-scale awareness, we will keep reporting our findings to all stakeholders involved.

Conclusion

Managing technical debt in Silverfin template development will be an ongoing journey. By following a structured approach, we have not only gained a clearer understanding of where technical debt exists in our codebase, but have also built a strong case for addressing it as a company-wide concern rather than just a development challenge.

Through close collaboration between engineering, product, and development teams, we’ve ensured that technical debt management is integrated into our long-term strategy, balancing short-term deliverables with long-term maintainability. The introduction of measurement frameworks and prioritization strategies has allowed us to make informed decisions, ensuring that our efforts yield the greatest impact.

Moving forward, we will continue to iterate on our approach, regularly reassessing and updating our documentation to reflect the evolving state of technical debt. By maintaining organizational awareness and embedding best practices into our development processes, we aim to create a more sustainable and efficient codebase—one that supports innovation while minimizing unnecessary complexity.