now I'm starting to understand how I want to present this

atuttle · atuttle · commit 2610a90a6e07 · 2023-03-03T09:50:40.000-05:00
diff --git a/blog/2023/what-to-do-when-drowning-in-technical-debt.md b/blog/2023/what-to-do-when-drowning-in-technical-debt.md
@@ -1,6 +1,6 @@
 ---
-title: My theory of technical debt (It's the business' fault)
-desc: If we're professional software engineers, why aren't we acting like professionals?
+title: What to Do When You’re Drowning in Technical Debt
+desc: An explanation of how to frame the discussion so that the business sees value in reducing and preventing technical debt.
 img: /img/2023/hunters-race-MYbhN8KaaEc-unsplash.jpg
 date: 2023-03-30
 tags:
@@ -16,30 +16,31 @@ Photo by <a href="https://unsplash.com/@huntersrace?utm_source=unsplash&utm_medi
 It's not _dark science_ or _rocket surgery_ to write decent software. You can get lucky and slap something together that works on the first try and never has problems, but you can't count on that luck to last your entire career. The good news is that there's a consistent and predictable way to write good software.
 
 1. Decide what feature needs to be written. If complexity necessitates, write a specification.
-2. Write tests that will validate when you've reached the goal. When the tests pass, stop working. If your tests are passing and you know there's more features to add or more edge cases to handle, then you need to add more failing tests first.
-3. Write the code that makes the tests pass, ignoring best practices.
-4. Refactor the code to follow all of those best practices you ignored in the last step. Fortunately you have the tests to give you confidence that you haven't broken anything!
+2. Write tests that will validate when you've reached the goal. When the tests pass, stop working. If your tests are passing and you know there's more features to add or more edge cases to handle, then you need to add more failing tests first.[^0]
+3. Write the code that makes the tests pass, ignoring best practices &ndash; get to passing tests as quick and dirty as you can!
+4. Refactor the code to follow all of those best practices you ignored in the last step. Fortunately you now have the tests to give you confidence that you haven't broken anything during your refactoring.
    1. Remove duplication
    1. Employ [SOLID principles](https://en.wikipedia.org/wiki/SOLID)
-   1. Make it readable for the developer who has to debug it in 10 years and doesn't know what you're thinking today. It might be you. Or it might not be.[^1]
+   1. Make it readable for the developer who has to debug it in 10 years and doesn't know what you're thinking today. It might not be you.[^1]
    1. etc...
 5. Submit for code review, and incorporate feedback as appropriate.
 
+[^0]: It is a legitimate strategy to write a prototype of the feature first before you write tests if you don't yet understand what it will take to implement the feature. You can't test something you don't understand, so write a throw-away prototype to learn from, then throw it away, and write your tests for the real implementation.
 [^1]: "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability." - [John Woods](https://stackoverflow.com/a/878436/751)
 
 ## Then, why is there always so much technical debt?
 
 **My theory is that we allow "the business" to get in the way of doing our jobs well.**
 
-Too often, software companies and IT departments are given a project mandate and an allowable time limit to spend working on it. Maybe they talked to customers about it, decided it would be a valuable project, and the customer would need it by a certain date in order to be able to use it.
+Too often, software companies and IT departments are given a project mandate and an allowable time limit to spend working on it. Maybe the CEO talked to customers about it, decided it would be a valuable project, and the customer would need it by a certain date in order to be able to use it.
 
 That's the wrong way to think about it.
 
 Even if we are diligent about only working on the parts that _really must be included_ and not getting sidetracked by things that are interesting, the phrase "it'll be done when it's done" is still right; regardless of whether the business wants it done in 3 months or 3 weeks.
 
-So you've accepted a project, and an unrealistic timeline. Now what?
+So you've accepted a project, and an unrealistic timeline. Now what happens?
 
-Well, you can't skip step 3, you've got to write the code. And step 5 (code review) seems like it could be a good safeguard against the problems that steps 1 (specification) and 2 (tests) protect you from (if people were perfect at code reviews, _which..._). And step 4 (refactoring)? You think the business is going to let you take code that's already working make it "better" without making any functional changes? That's going to go right out the window.
+Well, you can't skip step 3, you've got to write the code. And step 5 (code review) seems like it could be a good safeguard against the problems that steps 1 (specification) and 2 (tests) protect you from, and code review tends to take a lot less time the writing a spec and tests. And step 4 (refactoring)? You think the business is going to let you take code that's already working make it "better" without making any functional changes? That's going to go right out the window.
 
 What's left?
 
@@ -48,7 +49,7 @@ What's left?
 
 Sound familiar? I bet it does.
 
-Skipping those steps is where technical debt comes from.
+Skipping those steps is where technical debt is born.
 
 \* \* \*{style="text-align:center"}
 
@@ -68,7 +69,11 @@ You're not the guy who puts the sour cream on the tacos when they land in front
 
 \* \* \*{style="text-align:center"}
 
-Your job isn't to translate the human-readable specification into computer-readable code. It's to be a software engineer. When an architect or an engineer tells their customer that the request can't be completed in the given time, the customer will accept that and find other ways to make their building schedule work, or they'll have to find another architect or engineer.
+Your job isn't to translate the human-readable specification into computer-readable code. It's to be a software engineer. When an architect or an engineer tells their customer that the request can't be completed safely in the given time, the customer will accept that and find other ways to make their building schedule work, or they'll have to find another architect or engineer.
+
+The Archictects and Site Engineers _are_ responsible, and they _will_ be held accountable if the building crumbles.
+
+Everyone acknowledges safety is important. Shouldn't it be important in business software, too?
 
 If you know you're not being given enough time to complete the project well, refuse to sign the paperwork that says that you can be held responsible for failure, because you know it inevitably will.
 
@@ -88,17 +93,25 @@ The short version is that if the timeline must be fixed, then the scope must be
 
 You can have a fixed scope, or a fixed timeline, but not both.
 
-Prevention is the best cure, and that's what I'm championing here. If we as an industry start standing up for ourselves and enforce the right way of doing our jobs, then future technical debt can be minimized if not avoided entirely. And we can get some sleep, too!
+### Step 1: Stop the bleeding
+
+You'll never escape from technical debt if you don't slow down its creation.
+
+An ounce of prevention is worth a pound of cure. If we as an industry start standing up for ourselves and enforce the right way of doing our jobs, then future technical debt can be minimized if not avoided entirely. And we can get some sleep, too!
 
 ### But what about pre-existing technical debt?
 
-I am a big fan of [framing technical debt as "maintenance load"](https://stackoverflow.blog/2023/02/27/stop-saying-technical-debt/). It helps the business understand the true cost of technical debt: If your maintenance load is 50% then a 6 week project will take 12 weeks to complete. It also gives us, the engineers, a concrete objective to battle against. Identifying specific sources of maintenance load and reducing or eliminating them will (**measurably!**) improve the lives of the whole team, allow the department to ship projects faster, and help the business do... business things... better.[^3]
+I am a big fan of [framing technical debt as "maintenance load."](https://stackoverflow.blog/2023/02/27/stop-saying-technical-debt/) It helps the business understand the true cost of technical debt: If your maintenance load is 50% then a 6 week project will take 12 weeks to complete. It also gives us, the engineers, a concrete objective to battle against. Identifying specific sources of maintenance load and reducing or eliminating them will (**measurably!**) improve the lives of the whole team, allow the department to ship projects faster, and help the business do... business things... better.[^3]
+
+It could be a difficult conversation, but if you frame it as something concrete, and you bring actual metrics to the table to show the sources and cost of your current maintenance load, then you can have a real discussion about what can be done to reduce it and prevent it going forward.
+
+The business doesn't want to give you 3 weeks to make the software "better" without adding any new features, but spending 3 weeks to invest in shipping future projects faster, when framed in maintenance load terms, can be seen as a win even in their non-technical eyes.
 
 [^3]: I am so good at wording.
 
 ### Estimating: The Footgun of Software Engineering
 
-I don't have any silver bullets (yet?) for doing better at estimating, but I acknowledge that not every project is brought down from the mountain with a requirements doc and an unrealistic deadline pre-attached. Sometimes we estimate ourselves into this situation, and in those cases we have only ourselves to blame.
+I acknowledge that not every project is brought down from the mountain with a requirements doc and an unrealistic deadline pre-attached. Sometimes we estimate ourselves into this situation, and in those cases we have only ourselves to blame. I don't have any silver bullets (yet?) for doing better at estimating, but here are some thoughts to get you started.
 
 I've heard people say that they come up with their estimation, and then they double or triple it, and give that as the actual estimation, to cover anything they haven't thought of. That's one way to do it, though probably imprecise.
 
