Technical debt


 *  temporary solutions have a terrible habit of becoming permanent, around here

Overview
The Technical Debt Program has been put in place to help the Foundation and the broader community better understand and manage MediaWiki technical debt. This article's purpose is to help establish a common understanding of technical debt for the Foundation and the broader MediaWiki community.

What is Technical Debt and why is it important?
As put simply by Dan Rawsthorne - "Technical Debt is what makes code hard to work with."

Although simplistic, the spirit of the above definition is generally at the core of most industry experts’ own definitions.

The reason it’s important is because code that is hard to work with generally hampers developer’s productivity and results in less stable code.

All too often the term “technical debt” ends up being applied to a wide range of issues, and as such, becomes unmanageable. Technical debt is NOT a bug or the lack of a feature. Technical debt is not just a fancy name for “sloppy code”.

Technical debt is generally not visible to a user of the system. It’s visible to developers and those that have to work with the source code in some capacity. Although defects themselves are not technical debt, they can be a result of technical debt.

Taxonomy
I. Debt incurred unintentionally due to low quality work

II. Debt incurred intentionally

II.A. Short-term debt, usually incurred reactively, for tactical reasons

II.A.1. Individually identifiable shortcuts (like a car loan)

II.A.2. Numerous tiny shortcuts (like credit card debt)

II.B. Long-term debt, usually incurred proactively, for strategic reasons

Is Technical Debt Bad?
Often we are faced with the decision to take a shortcut in order to get code deployed faster or make progress in another area. Those shortcuts have a future cost, not unlike real debt. Do the short-term benefits of the shortcut outweigh the long-term costs? If so, it might be worth it. But as with any debt, accrual of the debt without plans to repay it is a bad idea. It leads to ongoing “interest” payments in the form of slower progress whenever working in that part of the code. So, if you consciously make a decision to incur the technical debt, do so with a plan to repay it as soon as possible.

Looking at the aforementioned Technical Debt Taxonomy, types I and IIA.2 should really be avoided at all costs. They generally don’t result in any near-term advantage and are generally difficult to track.

When deciding whether or not to take on technical debt, make sure that your stakeholders are involved in the decision. They will not only know what to expect in the near term, but also be able to support refactoring work later.

UX Debt
UX debt is similar to technical debt, rephrasing Dan Rawsthorne: " Technical Design Debt is what makes code designs hard to work with." UX debt is exposed to the users. This makes refactoring hard, because users get used to the (debt ridden) UX. After a refactoring of the design user may complain that the design "feels wrong" and that it lowers their efficiency (since the old usage strategies don't work anymore).

Causes of Design debt can be e.g.:


 * Design incoherence after several changes due to AB-testing
 * More and more elements have been added in controls that can only handle a few items well (e.g. Tabs)
 * E.g. We used to have all function in a little icon bar, but now that bar holds 15 functions, since more and more have been added.
 * Quick "hacks"
 * Like using an icon instead of a link, since it is smaller
 * Adding implicit modes like "If the user just has edited something, this button also does…" or "if you click in the empty space, function X is automatically called.
 * Paradigms change between different parts of the software, e.g.
 * VisualEditor uses a lot of popups, the "old" mediawiki uses dedicated pages, other parts may use sidebars, overlays…
 * A transition is not done yet, e.g. from jQuery UI to OOUI
 * Some pages have OOUI in the main area, but old buttons for "save" and "cancel" (like the Beta features page as of June 2017)
 * Wikidata builds on it's own style based on jQuery UI and does not yet use OOUI