How we tackled technical debt at Wikipedia

Talking a bit helped us write off several years of technical debt

A big challenge for any software engineer is explaining an important technical change to an audience who may not necessarily have the appropriate context. “Technical debt” is a phrase that will perplex a product owner if not articulated correctly. If you work in any product-centric team, you’ll likely find many technical tasks may be brushed aside in exchange for more tangible, visible outputs. That said, technical debt is very real and needs to be addressed.

A product owner responds to an engineer who has told them they need a feature freeze while a year is spent fixing some poorly defined technical debt without a clear outline of what that means (Source: Pixabay, free for commercial/non-commercial use.)

Back in January 2018, Wikimedia engineer Joaquin Hernandez and I pitched a one year project to pursue the scoped and measurable goal of increasing code coverage of our codebase and investing in our ageing but strategically important codebase. We did so with the belief that this could lead to working with code we liked much more.

Often developers, designers and product owners speak different languages and have very different and conflicting desires. Taking the time out to write the project proposal and talk together about problems, solutions and benefits was well worth the time and resulted in a shared mutual understanding. I believe that because of this work and new shared understanding, the project was easier to get onto our annual goals.

The problem statement

Our “stack” is a LAMP stack, with jQuery and some in-house (but open sourced) libraries you have likely never heard of. Given the age of our project, we still have several libraries that we can’t easily remove from our stack without breaking crucial and complicated tooling made by developers long gone that editors still use to keep Wikipedia running. For example, much of our site is built on jQuery UI which was released back in 2007. Our technical community has made good progress in pulling us away from these libraries by getting them off the critical path (JavaScript that is loaded without the user interacting with anything) and reducing redundancy.

A newly hired front-end developer inspects the dependency tree for Wikipedia’s mobile search functionality (Source: U.S. Department of Energy, public domain)