Ignoring this CADmandment will slowly and inevitably break your Documentation System.

As a system gets more complex (have you ever known one to get simpler?) a disconcerting number of the changes you make will inevitably have loose-ends,  inconsistencies, duplicates, orphans and WTF-was-I-thinking moments. The gap between what is documented and what is actually there will inevitably widen, as will the cracks in your documentation system. Documentation Systems crack and break at the joins. As an aside, remember – anything new also counts as a change.

I use the word inevitable here a lot. Initially it was an unconscious decision. I think it was a good one so I’m sticking with it. It is the natural order for things to flow along the path of least resistance. This is true for water and electricity and it is true for people also. One Version of the Truth is all about laying the foundation to make success inevitable, not failure. If you make it harder to succeed than fail then fail, you inevitably will. The system should be your servant – not the other way around. It is of your making. More on that another day. Oh, if you don’t have a documentation system – make one. Now.

What is One Version of The Truth ?

Do not store any information more than once. Ever.

What – you want more? ok but this is gunna be a long one. I promise that my future rants will be (mostly) more concise but this is The Big One. There is a fair bit of industry-specific jargon here which I will soon (I hope) write a glossary for. If the magic has happened (ie. I wrote them) then the jargonese should link to a explanation of said jargon. One day. I promise. Rightyo, this is what it all boils down to…

There should only be one root-source, one fountain of knowledge.

You may certainly derive a report from The Truth at any time but never treat this report as you would the original Truth. That report is an out-of-date and disconnected snapshot of The Truth from the moment it is generated. Spreadsheets, Cable Schedules etc are (usually) reports generated from the source of the truth – the schematic drawings. The reports should be clearly identified as such. They should be consciously labelled with the exact time they were generated so nobody ever forgets that this report was, at best, a snapshot of the truth. If you are looking for the truth for now then you must either regenerate this report or look elsewhere (in the racks, for instance, where the Real Truth lies). If the message that “This Is A Report From This Time” is explicit then it removes an inevitable gaping opportunity for misunderstanding.

Have you have ever wondered why a lot of wiremen prefer to work from schematics rather than cable schedules? It is because they implicitly know how the process (usually) works – the schematic gets updated then, later, the cable schedule (sometimes, eventually…) gets updated. They also know that if the cable schedule is generated manually (by a human scanning drawings) then it will inevitably contain tragic and expensive mistakes. It just does. They know this because they have seen it countless times.

This is of, course, not true if the cable schedule is indeed the oracle, the owner of the information. Then any drawings you have are simply reports of the cable schedule. That said, those drawings should be overviews only, deferring the details to the cable schedule which is the rightful owner of the nitty-gritty information.

Again – all reports should be clearly labelled as such so they are not assumed to be the original source. Sooner or later some poor Innocent will update them and then disaster will ensue. Suddenly the drawings and the cable schedules say different things and nobody knows which one is right or wrong. Odds are they are both wrong in the own peculiar ways.

Many things we do every day break the First CADmandment. Offsheet drawing references (manually adding a pointer from one drawing to the next) break this rule really, really badly. They never get updated. Manually cross-referenced room and rack layouts versus their respective schematics (also often versus the cable schedule) is probably the second-most prominent example of this. Stop and have a think about it – I bet you can name a scary number of everyday things you / we  I do that violate this rule. When you think of them, please add them to the comments below.

By making one place only the source of the truth you can easily find the real truth, and the source for the real truth – there should only be one place where you know you need to look to find the truth. Then, and only then, can you change the truth and be sure it will be, indisputably, the new truth.

Should we stop breaking the First CADmandment right now ?

My short answer is … YES! … eventually but you won’t be able to stop suddenly. Rome didn’t burn in a day. You / We / I will need to evolve our behaviour and practices – indeed our Documentation Systems – towards a model that reduces, if not eliminates, violations of CADmandment Number One, The One Version of The Truth. Strive for it. It is a difficult goal but it is, as far as a Documentation System goes, the most important goal. It is also probably one of the hardest goals. Oh, yay!

This is CADmandment Number One for a bloody good reason. Ignore it at your peril. If you choose to dismiss this CADmandment then you may as well dismiss the rest of my rants on this site. Seriously. This is the one problem that will cost you more time, heartache, swearing, tantrums (oh, that’s just me?) via inconsistencies, conflicts and mistakes, than anything else I have discovered so far. These stuff-ups always happen at the worst possible time. Oh, yes, You Know It.

Oh, and while I’m at it – forget about updating any information in reports – you’re shuffling deckchairs on the Titanic – today. That report is literally history. Generate a new report from the real information – the Truth.

Yes, I know this Article sounds pretty bullish and know-it-all. Take it from me – I don’t know it all. I will endeavour to not make it a habit but I make no apologies for this here and now. This CADmandment Number one is really important.  As an aside, a special thank-you to Catherine Eibner for introducing me to this concept. She knows stuff – lots of stuff.

So, do you agree, disagree or did I just confuse you? Please let me know your thoughts via a comment below.

More Reading:

http://en.wikipedia.org/wiki/Single_Source_of_Truth

http://www.computerworld.com/s/article/88349/Business_Intelligence_One_Version_of_the_Truth?taxonomyId=009

ok Folks, we’re in this together. What would you like me to address on this blog of ours? I’m looking for your feedback.

• Did I miss anything ?
• Got any burning questions?
• Did I mention a CADcept I haven’t yet defined ?
• Am I not making sense at all? Actually, please comment on the post that doesn’t make sense so we can keep those thoughts focused.

Please add a comment below with your suggestions and I will follow them up. All of them. Especially yours.

If I set up a forum you would need to register or use OpenID (which is a much better idea) to post on it. If you don’t know what OpenID is, follow the link – it is a great innovation.

If I get a few starters I’ll set one up.

I’m getting there. This site will soon evolve into community for Broadcast Engineering types who want their documentation systems to “just work”. I will soon be releasing some details of my grand plans to create software to take care of all the boring bits of Broadcast Systems documentation, specifically schematic CAD diagrams.

Also coming soon is my CADblog. I’ll be blogging short pieces on concepts, tips and tricks I have picked up in my years. The aim of that blog to to make your CADding life easier and more streamlined. There are a zillion ways to do these things so I will be encouraging discussions through the blog and forums. If you reckon I’m wrong about something then we all want to hear about it. If you have a better idea or a refinement then we’d all love to hear about that too. If you like kittehs well, there’s always LOLcats.

I’ll also be talking about the software development process and I’ll be asking for feedback on what you’d like to see and what you think isn’t so important after all.

Here is a page that outlines more of what I’m on about.

Stay tuned, there’s more to come. Soon.

Ewen
October 09