Been thinking of explaining technical debt using a book library as an example...
Say you want to start a lending library, you hire one person and stock 25 books. The stock is small and one person can easily remember all of them so the employee just piles them up in a corner. If a customer wants fiction or literature or whatever, the employee could easily look up the pile and pull it out.
Over time the books grows from 25 to 50, the stocks still small and there's just one employee so they are all just added to the pile.
50 grows to 150, you hire one more. The old guy feels that since there are two of them one can lookup the first 75 while the other can search the next 75 and organizing would a waste of time and space.
When you hit 500 books the debt starts to kick in but again you try to solve it by hiring more people. Some of the new hires want to categorize the books into proper racks but that would mean shutting shop for few days and not adding any new books. This is unacceptable to a non technical manager so things continue to be the old way.
By the time you hit 1000 books some of the employees are fed up with the time consuming work and quit, the replacements have no clue what is where. Most of the customers were served purely based on the muscle memory of the old employees and now that they have gone the business starts to crumble.
I especially like this metaphor! A codebase doesn't exist in a vacuum; a team of developers work on it and also produce auxiliary artifacts like configuration and documentation. The software only "works" so long as the whole system "works". When too much knowledge is held only by people, and isn't recoverable from the codebase and other desiderata, the whole enterprise (lower-case e) falters once that knowledge is lost.
I just finished reading The Name of the Wind, a fantasy novel where the organizational scheme of the library at a magical University is a minor plot point. Every time the school gets a new Master Archivist they come in with bright and ambitious ideas about how the catalogue should be organized and abandon their predecessor's scheme, with the result that centuries later there are dozens of overlapping and even explicitly competing systems extant in the library and many books are basically impossible to find. This, too, reminds me of basically every large codebase I've ever seen.
Reading this I just clicked the audiobook. Sounds like something I could love working as a technical oriented data analyst after having studied literature.
At one particular location at one of our favorite customers it was a mess to get out from their site every day after work.
Why? Because they collected everyones id-cards/drivers licenses etc in the gate on their way in and then dropped them into a box - unsorted.
This meant for everyone that wanted to leave they had to sift through the box.
Now my colleague asked them at one point why they didn't sort the id cards as they received them and got a scolding to the tune of "can't you see how busy we are already? Now imagine if we had to sort the cards as well!".
The next time he was there however it had sunk in and leaving was as fast (or faster) than arriving.
This is a good parable, but a bad metaphor: no one would open a staffed lending library with a collection so small that the staff could keep everything in their head. The key to a good metaphor is that it should hit something familiar and normal, so that the listener can devote their mental cycles only to the relevant understanding.
There are really two properties which are essential for a metaphor to convey understanding (which is not to say no other aspects have an effect—they certainly do, but I'm just trying to narrow down the 'functional core' here):
1. It needs to be expressed in the terms of a subject already understood by the listener.
2. It should have a 'structure' which is similar to that of the new, not yet understood subject.
These two things allow an identification to be made between something already understood and something not yet understood, granting new understanding.
The idea that the library should be 'normal' is not essential; it just needs to be understandable. (granted if it became too unusual it could cause problems, but I'll just leave it up to the reader's judgement whether "a library with 25 books" is too large a stretch of the imagination)
What's really nice about the above metaphor is that its structure matches the situation with coding very closely: technical debt is about the up front time-cost of introducing new systems of organization to replace ad-hoc, unsystematic methods whose cost-effectiveness decreases as project complexity (to put it loosely) increases.
While this is a pretty abstract notion in itself, the library scenario captures the same key points and dynamics in a way that's comprehensible to anyone with an understanding that libraries use 'systems of organization' (even if they don't know an abstract term for it)—this still works even if the particular set up for the 'library' in the example would not be found in the real world.
We’ll have to agree to disagree. I think a metaphor that has nothing to do with reality causes people to think too much about it. You end up replacing one abstract thing with another abstract thing (and the reason to go metaphoric in the first place is to make the concept less abstract). The metaphor makes more sense you because you’re already deeply familiar with the concept of technical debt so you’re able to easily evaluate (2) — you’re not actually using it for understanding. If I told this metaphor to my spouse (for whom I’m often using metaphors to explain things), the reaction would be: “What are you talking about? Library with 25 books? Huh?”
> (and the reason to go metaphoric in the first place is to make the concept less abstract)
I completely agree with you there. But I disagree that the unusual library example is more abstract.
As a point of contrast, I gave an abstract account of technical debt for the purpose of comparison to the more concrete library metaphor (to show that the abstract account would be more difficult for many):
> technical debt is about the up front time-cost of introducing new systems of organization to replace ad-hoc, unsystematic methods whose cost-effectiveness decreases as project complexity (to put it loosely) increases.
A library with 25 books is not more abstract, though it is a hypothetical concrete thing [1]. If someone has difficulty with hypothetical concrete things, that could certainly make using metaphors with them more difficult—and I can see why you would add additional constraints onto what makes a good metaphor. In my personal experience, saying, "imagine a library, but with only 25 books, which is run by a single person," would be not asking too much of an audience. But I see your point that some may struggle with it.
[1] There is a handy way of considering this distinction: becoming more abstract involves making some 'parameter,' which was fixed, free instead: so for instance a more abstract notion than any particular library is: a manager of a collection of objects which are loaned out to people for limited durations of time. In that example, we free the parameter 'book' so that it isn't set to anything specific. If we instead say, "a library but for CDs instead of books," it's equally concrete since we haven't freed any parameters, we just replaced one concrete value for another. That's what happened in the "library with 25 books" example, which is why I say it is not more abstract.
>2. It should have a 'structure' which is similar to that of the new, not yet understood subject.
If you'll forgive my pedantry, at this point you're not discussing metaphors and have veered into analogies. Maybe we can meet in the middle and call these metaphorical analogies? ;)
Metaphors are when you say something is something it is not ("my wife's smile is the bright sun I wake up to"). There need not be anything unfamiliar with a metaphor or any explanatory power behind a metaphor. Analogies are when you explain or frame a concept using an already understood concept ("the car is out of gas, like when you're out of energy and don't want to run around.")
As an aside, I'll mention that the idea that "analogy as the core of cognition"[0] has been kicking around in academia for years, and comes from Douglas Hoffstader (author of Gödel, Escher, Bach).
> There need not be anything unfamiliar with a metaphor or any explanatory power behind a metaphor
The purpose is still explanatory, it's just possible for the explanation to be in terms of perceptions rather than structure: in your example with wife/bright sun the purpose is still to make an identification between two domains, one familiar, one not ("bright sun" is familiar to the reader; author's wife is not), but rather than the two being "structurally similar" it's that they evoke similar experiences in the author, and the author is able to explain their experience by sharing this identification.
That said, I agree with you that what I was discussing is closer to definitions of analogy in certain areas of cognitive science (e.g. Hofstadter's work, like you've pointed out—or John Sowa's: http://www.jfsowa.com/logic/theories.htm)
But the original example with the library would've been better termed an analogy to begin with, rather than a metaphor—I just adopted the previous commenter's terminology :) (though admittedly I'm more inclined to interchange the two fluidly because I don't find the differences essential: I would just call the kind of metaphor you used a perceptual analogy. Maybe I am missing something important about metaphor though—I'd be curious to hear if so!)
I tend to agree with him. It takes too long to tell that story. In a boardroom meeting type environment people don't have time or the attention span to settle in for story time. You need to be able to illustrate your point in 3 sentences or less.
Whenever I had to explain it to management I tell them something along the lines of:
When was the last time you clean your office cupboard? If anyone else from management needs to find something in there without your help how long would it take compared to you?
It's the same with our scripts. They need cleaning up and documenting in case one of us decided to call it a day.
Edit: When the situation allows(tbh I rarely miss a chance) I follow up with: You have to thank our sales guys making unrealistic promises for our lack of documentation.
that is pointless. It isn't about message, it is all about messenger. If they don't want to listen to you, they wouldn't. My friend who has made his way pretty high here in the SV told me recently how the same CXX/"boardroom" people who wouldn't listen even to his 1 sentence, now have all the time and attention in the world to listen to him all day long.
This is true. You can always try to convince people but if you're not string puller, you're in mercy of listeners. If they fix on something (e.g.profit, own promotion), your story should be aligned to that(their KPI). Then only you can have hope.
When shit breaks, no one wants to take blame and people start to forget 'selectively' your earlier warnings of shit.
Say you want to start a lending library, you hire one person and stock 25 books. The stock is small and one person can easily remember all of them so the employee just piles them up in a corner. If a customer wants fiction or literature or whatever, the employee could easily look up the pile and pull it out.
Over time the books grows from 25 to 50, the stocks still small and there's just one employee so they are all just added to the pile.
50 grows to 150, you hire one more. The old guy feels that since there are two of them one can lookup the first 75 while the other can search the next 75 and organizing would a waste of time and space.
When you hit 500 books the debt starts to kick in but again you try to solve it by hiring more people. Some of the new hires want to categorize the books into proper racks but that would mean shutting shop for few days and not adding any new books. This is unacceptable to a non technical manager so things continue to be the old way.
By the time you hit 1000 books some of the employees are fed up with the time consuming work and quit, the replacements have no clue what is where. Most of the customers were served purely based on the muscle memory of the old employees and now that they have gone the business starts to crumble.