├── LICENSE ├── CONTRIBUTING.md └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 James Hawkins 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # 🎉 Welcome Contributors! 2 | 3 | We would **love** to have you suggest ideas for this list. Here are our guidelines: 4 | 5 | ## If in doubt, ask - we're friendly 6 | 7 | Some communities can be a little intimidating, and we want to make it as inclusive as possible. 8 | 9 | We want to encourage you to suggest useful additions to this list. If you want any help or to ask about something, just email james-os@hiberly.com, and I'll get back to you asap! 10 | 11 | ## Look for original sources 12 | 13 | There are lots of articles that just repeat other articles. Try to get to the bottom of this chain with the suggestions you make - don't give an article quoting another article, get the one it all started with. However, if the article you submit adds considerable value, that's ok. 14 | 15 | ## We prefer non-commercial content 16 | 17 | We've chosen to publish this as open source to keep things more neutral. 18 | 19 | It can be unavoidable to have a certain degree of commercial content - the quality bar needs to be higher for it to be included. For example, we decided to include the [PagerDuty toolbox](https://postmortems.pagerduty.com/), because it is high enough quality. 20 | 21 | Pro-tip: with research papers, many of them are gated behind a paywall, but are then freely available elsewhere on the web, please have a look first and make it clear if the resources is a paid paper. 22 | 23 | ## Link to the author where possible 24 | 25 | If people are putting great stuff out there, they deserve credit! Make an attempt to link to the author in the description of the piece. We've defaulted to Twitter, but a personal website, GitHub profile or LinkedIn could all help people get in touch if they want to. 26 | 27 | ## Label the content type 28 | 29 | Our preference is to find written content as it is usually the most practical to digest. However, failing that, other forms of content where they are very strong are fine. In particular, if there is a book that you feel is the best source of truth for a topic, do add it but please make clear that it is a book and needs buying! -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Tech Debt - Prevention, Diagnosis and Cure 2 | 3 | A tech debt reading and resources list. It contains lots of ways to diagnose, prevent and control tech debt. 4 | 5 | This is a WIP! Please add any resources you find interesting by creating a fork and creating a pull request. 6 | 7 | **Table of Contents** 8 | 9 | - [🏁 Start here](#-start-here) 10 | - [🎖 Case Studies](#-case-studies) 11 | - [⛔ Prevention](#-prevention) 12 | - [🤝 Requirements](#-requirements) 13 | - [📡 Infrastructure](#-infrastructure) 14 | - [🏛️ Architectural](#-architectural) 15 | - [🎨 Design](#-design) 16 | - [💻 Code](#-code) 17 | - [✅ Testing](#-testing) 18 | - [🛠️ Build](#-build) 19 | - [📝 Documentation](#-documentation) 20 | - [🏚️ Versioning](#%EF%B8%8F-versioning) 21 | - [🏥 Remediation](#-remediation) 22 | - [🔍 Post Mortems](#-post-mortems) 23 | - [💣 High Interest Debt First](#-high-interest-debt-first) 24 | - [🧭 Boy Scout Rule](#-boy-scout-rule) 25 | - [🧰 Tools](#-tools) 26 | - [Contributing](#contributing) 27 | - [Authors](#authors) 28 | - [License](#license) 29 | - [Sponsors](#sponsors) 30 | 31 | ## 🏁 Start here 32 | 33 | [What is tech debt](https://www.youtube.com/watch?v=pqeJFYwnkjE) 34 | 35 | * [Ward Cunningham](https://twitter.com/WardCunningham) coined the term "tech debt". 36 | * Talks about history, motivation and common misunderstanding of the "debt metaphor" for refactoring. 37 | 38 | [Classifying Technical Debt](https://martinfowler.com/bliki/TechnicalDebtQuadrant.html) 39 | 40 | * [Martin Fowler](https://twitter.com/martinfowler) makes two disctions (1) prudent and reckless debt, and (2) deliberate and inadvertent debt. A classic 41 | 42 | [Identifying when Technical Debt needs action](https://blog.crisp.se/2013/10/11/henrikkniberg/good-and-bad-technical-debt) 43 | 44 | * [Henrik Kniberg](https://twitter.com/henrikkniberg) argues that older tech debt is bad, whereas new tech debt is acceptable in order to build prototypes. 45 | * Concept of a qualitative debt ceiling technique to manage the level of technical debt. 46 | 47 | [The Human Cost of Technical Debt?](https://daedtech.com/human-cost-tech-debt/) 48 | 49 | * [Erik Dietrick](https://twitter.com/DaedTech) goes into depth for how technical debt can harm teams. 50 | * There includes discussion on (1) unpleasant work (2) team infighting (3) atrophied skills (4) turnover and attrition. 51 | 52 | ## 🎖 Case Studies 53 | 54 | [Ticketmaster](https://tech.ticketmaster.com/2015/06/30/what-ticketmaster-is-doing-about-technical-debt/) 55 | 56 | * Step-by-step guidance on how Ticketmaster assessed their technical debt over 12 months. 57 | 58 | [Stripe](https://www.infoq.com/presentations/stripe-technical-debt/) 59 | 60 | * [Will Larson](https://twitter.com/lethain?lang=en) explains how Stripe use migrations to get away from tech debt. 61 | 62 | [A large bank](http://neopragma.com/index.php/2019/03/30/technical-debt-the-man-the-metaphor-the-message/) 63 | 64 | * [Dave Nicollete](https://twitter.com/davenicolette) covers a detailed case study, with costs, of resolving prudent-intentional debt. 65 | * Costs of the cleanup and the business impact included. 66 | 67 | [Optimizely design debt approach](https://medium.com/design-optimizely/pay-down-design-debt-with-polish-day-867eb59dd83d) 68 | 69 | * [Dave Rau](http://daverau.info/) explains how when Optimizely got to 50 UI issues, they decided to do something about it. 70 | * The team ran a 'Polish Day' once a week, with a points system for designers to prioritize work. 71 | 72 | [Paddy Power](https://www.researchgate.net/publication/271635510_Continuous_Delivery_Huge_Benefits_but_Challenges_Too) 73 | 74 | * [Lianping Chen](https://twitter.com/lianpingchen)'s article explains why the Paddy Power team decided to adopt Continuous Delivery, and explains the benefits and challenges involved. 75 | 76 | ## ⛔ Prevention 77 | 78 | ### 🤝 Requirements 79 | 80 | [Creating a Product Canvas](https://www.ebgconsulting.com/blog/using-product-canvas-define-product-getting-started/) 81 | 82 | * [Ellen Gottesdiener](https://twitter.com/ellengott) provides a canvas to convey what the product is, and how it is strategically positioned. 83 | * The first part of the canvas comes _before_ everything else and gives the context. It goes from vision through other high level areas such as revenue, competitors, and the innovation landscape. 84 | * The second part of the template is used to explain product requirements. 85 | 86 | [Story Mapping](https://www.jpattonassociates.com/the-new-backlog/) 87 | 88 | * [Jeff Patton](https://twitter.com/jeffpatton) invented the concept of Story Mapping (you can see a [video of this process](https://www.youtube.com/watch?v=XzaCaW8c3qE) here) 89 | * Flat product story backlogs are hard to understand - they are just a pile of features. By visualising an entire system with it can be much easier to spot opportunities or weaknesses, or indeed to work with other stakeholders in requirements gathering. 90 | * Create a series of cards with big stories (activities) at the top, down to tasks and then sub tasks. 91 | 92 | [Joint Application Design](https://www.pmi.org/learning/library/determining-project-requirements-best-practices-7278) 93 | 94 | * This is a thorough run-through by the Project Management Institute for Joint Application Design. It gives guidance on how to run design sessions for multi-stakeholder requirements gathering. 95 | 96 | ### 📡 Infrastructure 97 | 98 | [DevOps 101](https://opensource.com/article/19/4/devops-pipeline) 99 | 100 | * [Bryant Son's](https://twitter.com/bryantjiminson) simple guide that guides you through the basic setup to enable you to build you first pipeline 101 | * Covers (1) CI/CD Tools (2) source control management (3) build automation (4) web app servers (5) code testing coverage 102 | 103 | *TODO*: Add better DevOps resources here 104 | 105 | ### 🏛️ Architectural 106 | 107 | [Practical tips on Software Architecture Design](https://medium.com/@mbue/practical-tips-on-software-architecture-design-part-one-1c6bb0167157) 108 | 109 | * [Marco Bürckel ](https://twitter.com/mbue86) gives a good 101 on how to architect a system, starting with what to do before you pick a software deign pattern, through to functional and non-functional requirements and iteration. 110 | 111 | [Understanding software design patterns](https://opensource.com/article/19/7/understanding-software-design-patterns) 112 | 113 | * [Bryant Son](https://twitter.com/bryantjiminson) provides detailed diagrams explaining different software patterns, including (1) Singleton (2) Factory (3) Observer, with code examples for each. 114 | 115 | [Software Architecture Patterns](https://www.oreilly.com/library/view/software-architecture-patterns/9781491971437/) 116 | 117 | * [Mark Richards'](https://twitter.com/markrichardssa) book, fully available for free, gives an overview of (1) layered architecture (2) event-driven architecture (3) microkernel architecture (4) microservices architecture (5) space-based architecture. 118 | * Within each section, there is a run through of the circumstances that are appropriate for each architectural type. 119 | 120 | ### 🎨 Design 121 | 122 | [What is design debt?](https://uxdesign.cc/what-is-design-debt-and-why-you-should-treat-it-seriously-4366d33d3c89) 123 | * An extensive run through by [Michal Mazur](https://twitter.com/mazi_mazur), from his experiences at Kurt Geiger, where they had people drop out of the funnel because of inconsistent design. 124 | 125 | [Marginal Brand Degredation](https://markboulton.co.uk/journal/marginal-degredation/) 126 | * Just 1.6% is the difference in DNA between a gorilla and a human. [Mark Boulton](https://twitter.com/markboulton) uses a powerful analogy to explain the importance of marginal brand degradation. 127 | 128 | [Design Systems](https://github.com/alexpate/awesome-design-systems) 129 | * An enormous set of example design systems collated by [Alex Pate](https://twitter.com/alexjpate) 130 | * Covers components, voice and tone, designers kit and source code availability. 131 | 132 | [Primer Interface Guidelines](https://github.com/primer/design) 133 | * Repository to generate documentation for UI patterns and interaction guidelines. 134 | 135 | ### 💻 Code 136 | [SOLID Principles of Object Oriented and Agile Design](https://www.youtube.com/watch?v=TMuno5RZNeE) 137 | 138 | * [Bob Martin](https://twitter.com/unclebobmartin) ('Uncle Bob') explains software design principles. 139 | * This covers the principles of: Single Repository, Open Closed, Liskov Substitution, Interface Segregation, Dependency Inversion 140 | 141 | ### ✅ Testing 142 | [Test Driven Development](https://www.eecs.yorku.ca/course_archive/2003-04/W/3311/sectionM/case_studies/money/KentBeck_TDD_byexample.pdf) 143 | 144 | * [Kent Beck](https://twitter.com/KentBeck) came up with the concept of Test Driven Development (TDD) 145 | * Test Driven Development is defined by writing tests before writing any functionality. 146 | 147 | ### 🛠️ Build 148 | [Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html) 149 | 150 | * [Martin Fowler](https://twitter.com/martinfowler)'s overview explains how Continuous Integration - where members of a team integrate their work frequently, usually daily by each developer - can ensure the codebase is more coherent and bugs are easier to find. 151 | * The article covers the practices, but also the benefits and how to introduce Continuous Integration into the way a team works. 152 | 153 | [Continuous Delivery - a systemic review of approaches](https://ieeexplore.ieee.org/document/7884954) 154 | 155 | * This paper represents a state of the art, based on peer-reviewed papers from 2004 to 2016, by [Mojtaba Shahin](https://twitter.com/mojtabashahin), [Ali Babar](https://twitter.com/alibabar?lang=en), and [Liming Zhu](https://twitter.com/limingz). 156 | * The paper identifies 30 approaches and associated tools, including succesful applications to both greenfield and existing codebases, with the issues and opportunities that continuous practices summarised. 157 | 158 | ### 📝 Documentation 159 | [Real life examples of great documentation](https://www.atlassian.com/blog/add-ons/5-real-life-examples-beautiful-technical-documentation) 160 | 161 | * [Katrina Morales](https://twitter.com/katrinahmorales) gives examples covering (1) providing answers fast (2) creating community through comments (3) great navigation (4) design (5) rich content. 162 | 163 | [Extreme Programming Documentation](https://ronjeffries.com/xprog/articles/expdocumentationinxp/) 164 | 165 | * [Ron Jeffries](https://twitter.com/RonJeffries), one of the three founders of Extreme Programming, covers the documentation of (1) requirements (2) design (3) code (4) manuals. 166 | 167 | [The Eight Rules of Good Documentation](https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation) 168 | 169 | * This excerpt from [Adam Scott](https://twitter.com/adamdscott)'s '[Collaborative Web Development](https://www.safaribooksonline.com/library/view/collaborative-web-development/9781491996096/?_ga=2.191768554.1140860929.1571121117-2134570287.1570721867)' book, walks through not the "what" of documentation, but the "how". 170 | 171 | ### 🏚️ Versioning 172 | [Version control best practices](https://www.git-tower.com/blog/version-control-best-practices/) 173 | 174 | * A simple set of rules from [Tobias Günther](https://twitter.com/gntr), the founder of Tower (a Git client) hat will help make sure the whole team can work with the commits that each developer makes. 175 | 176 | [Writing good commit messages](https://chris.beams.io/posts/git-commit/) 177 | 178 | * You will default into messy commit messages. [Chris Beams](https://twitter.com/cbeams) shows what good looks like. 179 | 180 | ## 🏥 Remediation 181 | 182 | ### 🔍 Post Mortems 183 | 184 | [PagerDuty Toolbox](https://postmortems.pagerduty.com/) 185 | 186 | * PagerDuty have put together a completely all encompassing set of templates and an approach to the Post Mortem. 187 | 188 | [Language to use, understanding causation, and how to share](https://fractio.nl/2015/10/30/blame-language-sharing/) 189 | 190 | * [Lindsay Holmwood](https://twitter.com/auxesis) discusses how a thoughtful approach to learning from failure is key. 191 | * When to use "how" versus "what" versus "why". 192 | * Confirmation and hindsight bias. 193 | * Creating a safe culture to discuss failure. 194 | 195 | ### 💣 High Interest Debt First 196 | 197 | ['State of the Art - research summary'](https://arxiv.org/pdf/1904.12538.pdf) 198 | 199 | * 38 research papers summarised found there isn't a distinct "best practice" that has become clear yet. 200 | * Code and architecture are by far the two most focussed on areas, yet there are many more forms of debt (requirements, and tests, for example). 201 | 202 | ### 🧭 Boy Scout Rule 203 | [The Boy Scout Rule explained](https://dev.to/_arunsasi/the-boy-scout-rule) 204 | 205 | * [Arun Sasidharan](https://twitter.com/voidmaindev) creates a great explanation of [Bob Martin](https://twitter.com/unclebobmartin)'s rule. 206 | * The premise is to create a culture of leaving the code in a better state than when you started. 207 | 208 | ### 🧰 Tools 209 | * Continuous tracking of Tech Debt based on merges: [Hiberly](https://hiberly.com) 210 | * Code coverage, Cyclomatic complexity: [Sonarqube](http://www.sonarqube.org/) 211 | * Time to Interact: [Yottaa](http://www.yottaa.com/) 212 | * Application security: [Veracode](http://www.veracode.com/) 213 | * Infrastructure performance: [Splunk](http://www.splunk.com/) 214 | * Scalability: [SOASTA](http://www.soasta.com/) 215 | 216 | ## Contributing 217 | 218 | Please read [CONTRIBUTING.md](/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. 219 | 220 | 221 | ## Authors 222 | 223 | * **James Hawkins** - *Initial work* - [jamesefhawkins](https://github.com/jamesefhawkins) 224 | * **Tim Glaser** - *Editing* - [timgl](https://github.com/timgl) 225 | 226 | ## License 227 | 228 | This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details 229 | 230 | ## Sponsors 231 | 232 | [Hiberly Logo](https://hiberly.com?utm_campaign=os&utm_medium=techdebtreadinglist&utm_source=sponsorship) 233 | 234 | Hiberly prioritizes tech debt by grabbing feedback from developers after each merge. 235 | 236 | You can then draw cool graphs of your code versus happiness / frustration to help explain the impact of refactoring. 237 | --------------------------------------------------------------------------------