There should only ever be One Version of the Truth in any documentation system,in anything that involves the management of data, especially where the data is timely and subject to change. This I decree to be CADmandment Number One. To continue the Biblical reference, shunning this is the the root of all documentation evil. Most problems you will have with a data or documentation system can eventually be traced back to this root cause. ok, that’s enough of the Biblical references.
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.
This is very helpful advice, but in practi[s or c]e, time usually forces you/me to “update the documentation later” which then only happens after all the notes have been lost or tweaks forgotten. Still I am aiming at using CAD to build a virutal structure of my workplace including pipes, cables, vegetation (this is important) and anything else that could have an influence in supporting employed workers, replacements and contracted external persons. In a fantasy world I would like monitors that would compare the virtual model and the physical reality to determine updates, breaks, faults, and provide security.
That was my rant.