My Jekyll Doesn’t Hide

Client Visibility of Technical Debt Over Feature Stories

Carly Richmond
4 min readFeb 17, 2019


We all know that old idiom about skeletons in the closet. And the other advising us not to air our dirty laundry in public. Secrets in life are constructs that we prefer to keep hidden to prevent public shaming.

Many monsters lurk in our legacy code due to a lack of discipline in addressing technical debt

Secrets are also common to our technology platforms. Technical debt is lurking in every corner of our legacy systems. When not addressed in a timely fashion, these items become more costly to remedy. Without discipline, our newer platforms can suffer the same fate.

Hiding certain misgivings may be human nature. However, lack of transparency with clients in the accrual and remediation of technical debt is a common pitfall in software development practice. This week I reflect on the lack of transparency of technical debt with feature stories, and the need for product teams to engage with clients in prioritisation of all items together.

Hide Away Blues

My understanding of why technical hygiene tasks may be better off hidden doesn’t just stem from empathy. Our current setup purposefully hides it. A separate backlog of hygiene items is maintained and shared among multiple squads. While this approach has lead to a reduction of known debt over the years, we’ve also been presented with mixed results.

If technical debt is not repaid promptly, the cost of implementation increases exponentially

Small items are tackled easily with this approach, without severely impacting functional achievements. The value of regularly addressing smaller hygiene items should not be underestimated. This can introduce ownership issues for small items such as minor library upgrades. Those can be handled along with regular development if collective ownership is instilled.

Yet the challenge remains on the handling of larger remediations. These tend to undergo the pass the parcel treatment. No matter how many developers make progress on the item, the final feature takes significant time to complete.

Somethin’ to Hide

Legacy systems introduce significant challenges to hygiene transparency. The aforementioned sizeable items exist purely for lack of effort while they were easier to manage. In our case, we’re now having to pay the accrued interest. Our newer components don’t suffer from these trials.

Hiding hygiene items in the closest projects a false impression on system reliability

Yet our hidden hygiene history paints a picture that these systems are reliable, supportable and maintainable. In reality, these systems are rarely changed. Therefore older library dependencies are still utilised. Changes are as a result painful to implement as an upgrade of several versions requires more extensive testing, and manual at that due to lack of automated tests.

Motivating developers to undertake extensive work on such systems is challenging. Sure the sense of achievement at the end is such a high. Nevertheless, strong leadership is required to recognise and reward these efforts.

Where Do I Hide?

Once remediation is complete, senior stakeholder education is another hurdle we must jump in the race to production. If these items have not been transparent from the beginning, business sign-off of the changes and resulting testing are difficult to obtain.

Engineers need to be comfortable explaining the reasons for remediating technical debt in language clients can understand

The primary motivation for discussing post-implementation appears to stem from the technologist’s inherent fear of explaining the technical details in a comprehensible format. On a small level, I’ve witnessed engineers object to explaining the technical detail on stand ups when Business Analysts and the Product Owner are present. Like any skill it needs to be refined over time, and I would suggest regular discussions to justify why we are undertaking such hygiene work is appreciated far more than a last minute heads up.

Once hygiene work is completed, does it become any easier to justify why the work is secretly prioritised? By not being transparent with these items, we are failing to trust that a non-technical Product Owner will engage and understand why quality and reliability are important. A common backlog of feature and technical debt items is the sole mechanism for building mutual trust.

Hide And Seek

I’ve recently discovered that hiding of technical debt is not limited to just my team, but is an endemic problem across larger organisations. These fears are not limited to explaining to business stakeholders, but senior technology management as well. One colleague raised a concern that explaining these items can result in management becoming bogged down in unnecessary detail.

Transparency, transparency, transparency

Transparency is the key to Agile adoption. Ownership of the plant is a collective effort between business and technology stakeholders. A regular complaint is that business units don’t engage with Agile adoption. That clients provide insufficient time to support technology in the development of new features. If technology wants to be treated as an equal partner, they need to be transparent with the work they are undertaking to maintain the old, as well as build the new.

Thanks for reading. Don’t hide your thoughts and claps!



Carly Richmond

Developer Advocate with a strong interest in UI, UX, Usability and Agility. Lover of cooking, tea, photography and gin! All views expressed are my own.