Do You Know What Your System *Actually* Looks Like?

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 “throw them in the deep end” is what you do, well, I guarantee you that there are vast swathes of the systems that are equally “deep-end”-ish to you!

Let’s take this a bit further, and think about the different ways in which you probably don’t know your system well (or well-enough. Either can be a killer!)

1. Legacy: What about all the legacy code that you’ve got? Remember, 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, etc! Is that accurate? What’s more, every time somebody does something to legacy stuff, is the test coverage maintained and accurate?
2. Everybody Knows: What about all the Oral Tradition in the company? Of course you know it, because, well, “Everybody Knows that Alice’s GitHub account needs to be removed from your Organization after she leaves”, 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 anything that relies on Humans Doing The Right Thing is guaranteed to eventually fail!
3. The Bus Factor: 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 1. And yes, that includes all the times somebody doesn’t document a process.

4. 
   

   
   

   
   

   
   

   
   

   Complexity as an Excuse: If I had a nickel for every time I heard “It’s too complex to document”, well, I’d have a lot nickels. This is a classic code-smell, and one frequently deployed by #CowboyDevelopers. 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.

5. 
   

   
   

   
   

   system vs System: It’s so easy to think of systems as the software components of the product, when it’s actually much greater. Systems (capital-S) 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?

6. Oh Those Metrics: You do use metrics to make decisions, right? Do you track the ones that you do use? And use them consistently? After all, marching forward with ad-hoc data leaves you in your own bubble of local optima rules, and worse, leaves you using intuition (which will fail you at the worst possible time!! And, by definition, if you’re not being consistent around this, you don’t really know how your system operates, right?

So yeah, “Do You Know What Your System *Actually* Looks Like?” — 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.

(This article also appears on my blog)