If you’re good (or lucky), you actually know — and have documented — what your system looks like.Then again, do you? Really? For example, what happens when you’re on-boarding somebody — is there a process by which they’re brought up to speed? If “ ” is what you do, well, I guarantee you that there are vast swathes of the systems that are equally “deep-end”-ish to you! throw them in the deep end Let’s take this a bit further, and think about the different ways in which you probably know your system well (or well-enough. Either can be a killer!) don’t : What about all the legacy code that you’ve got? Remember, , etc! Is that accurate? What’s more, every time somebody does something to legacy stuff, ? Legacy legacy includes all the code that you’re written in the past, the skills that you’re not actively exercising, the components that were written by ex-employees is the test coverage maintained and accurate : What about all the Oral Tradition in the company? Of course you know it, because, well, “ , right? Then how come it wasn’t? Information that is either not actionable, or not acted upon, isn’t directly useful, is it? You have documented processes, because ! Everybody Knows Everybody Knows that Alice’s GitHub account needs to be removed from your Organization after she leaves” anything that relies on Humans Doing The Right Thing is guaranteed to eventually fail : What happens if Bob gets hit by a bus? Is there somebody else that knows everything he knows? You’d be surprised how many times Knowledge is distributed across the company with a replication factor of . And yes, that includes all the times somebody document a process. The Bus Factor 1 doesn’t : If I had a nickel for every time I heard “ ”, well, I’d have a nickels. This is a classic code-smell, and one frequently deployed by . Seriously, if it’s that complex, then either• It needs to be refactored into something simpler• It needs to be broken up into less complex components• It’s being done wrong• It’s just lazinessThat’s it. No other excuses. Complexity as an Excuse It’s too complex to document lot #CowboyDevelopers : It’s so easy to think of as the software components of the product, when it’s actually much greater. (capital- ) include the software, as well as the people, processes, internal and external dependencies, timing and timeframes, and a whole bunch more. • If it takes a new developer 6 months to come up to speed on your product, you better have hired them 6 months before you need them, no?• Your distributor only ships when you have a positive account balance, and takes 3 days to process payments. You better stay on top of your supply-chain, no?I could go on, but the point should be obvious — the items above, such as people, timeframes, supply-chains, etc. are as integral to your System as the code that you write. It behooves you to know this, eh? system vs System systems Systems S : You use metrics to make decisions, right? Do you track the ones that you do use? And use them consistently? After all, marching forward with data leaves you in your own bubble of local optima rules, and worse, leaves you using intuition (which fail you at the worst possible time!! And, by definition, if you’re not being consistent around this, you don’t really how your system operates, right? Oh Those Metrics do ad-hoc will know So yeah, “ ” — so much nuance packed into such a simple question, eh?My accursed paranoia around all of the above is pretty much why I get accused, all too frequently, of having a Documentation Fetish. And frankly, it’s worth it, I far prefer to add that load, as compared to being beholden to Murphy’s Law all the time. Do You Know What Your System *Actually* Looks Like? ( This article also appears on my blog )
