In hisThe Iceberg Secret, Revealed blog post,Joel Spolsky compares software with icebergs:

You know how an iceberg is 90% underwater? Well, most software is like that too — there’s a pretty user interface that takes about 10% of the work, and then 90% of the programming work is under the covers

Later in his text, he lets us in on a little secret:

People who aren’t programmers do not understand this.

And what's even harder for people who are not programmers to understand is how bad the "underwater" part can be (especially if the visible part looks fine). It can be hard to grasp, it can have fixes that are software development versions of duck taping a bike tire, it can be poorly or non documented...

You know what I'm talking about.Technical Debt. Just hearing the word makes your spine shiver. And communicating this to non-programmers can be very hard because

for a component that appears to be working, a non-programmer will assume the technical debt is minimal, or nonexistent.

During hisDealing with legacy code talk at theSoftware Craftsmanship meetup in Berlin,Michal Feathers briefly mentioned a technique of displaying technical depth visually. I didn't catch the name of the technique so I got him to write me a not after the talk:

It took some deciphering but I managed to get to the source. It wasColin Breck, an engineer/team lead at Tesla.

Inspired by a few different sources (including Michael Feathers talk onConway’s Law) he developed a

way to represent complex systems, or systems that are not customer-facing—like infrastructure platforms—to people who are non-technical, or not intimately familiar with the software.

The main information this representation conveys is the internal quality of the system components. Hence the name,Quality Views.

The idea is rather simple. First, you represent your system with an architecture graph.

The size of the elements represents the "relative size of the servers in terms of memory, cores, and IO capacity". For example, legacy load balancer servers are smaller than the "new" ones. Dashed lines represent system boundaries and the arrows show the flow of data (the thicker the arrow the bigger the flow). So, a nice graph rich in information but nothing new. I'm sure you've drawn a graph or two similar to this one.

The next thing that Colin does is he adds "information related to software quality and how the system is evolving" to this graph.

The way he does that is rather simple. The quality is color-coded. So, in this case, the closer to red the worse the quality.

To evaluate the quality of each component Colin developed a set of criteria, with each criterion contributing to the overall quality grade of a component. His criteria are:

• Code
• Tests
• Deployment
• Monitoring
• Alerting
• Security
• High-Availability
• Scalability
• Risks

And for each, there is a set of questions who serve as a checklist for each grade. Now, this is a set of criteria he developed for his use case, you can (and probably should) develop your own set of criteria. Also, you can introduce weights to these criteria because not all of them may be of the same importance to you.

Once you have your criteria set, you get a nice visual representation of Technical Debt that everyone, including non-technical people, can understand. Now, when planing a new feature, your manager can know how risky it is given the quality of components it requires work on. Also, this graph highlights the things you are not working on. And the risk of having a lot of (or relying on) low-quality components becomes harder to ignore since it's constantly present in this visual display.

Another thing, that can be a side effect of using Quality Views, is that it can also motivate your team. Internal code/infrastructure improvements often don't have a direct tangible effect on the application (the visible part of the iceberg) and using a quality view will give your developers (as well as PMs) just that - a tangible visual representation of the improvements done.

If you wish to explore Quality View more deeply I suggest you watch the presentationUsing Quality Views to Tackle Tech Debt @Tesla Colin gave at QCon London, as well as reading his two blog posts on the subject:Using Quality Views to Communicate Software Quality and Evolution andReflections on Using Quality Views.

* images are taken fromhttps://www.infoq.com/presentations/quality-views-technical-debt/