Cfengine 3 Syntax Part III (or, How to debate smart people in 140 character snippets)

More conversations with Mark Burgess via Twitter (a continuation from here. I should note that this was all a week or so ago now; I've been meaning to put this up here.

markburgess_osl: @saintaardvark Doc is "what" code is "how". I believe the lasting intention comes before a specific implementation. #devops #sysadmin

saintaardvark: .@markburgess_osl Hm. So let's see if I've got this right: the programmer in me notices lots of overlap in my Cf3 config...

saintaardvark: .@markburgess_osl ...and wants to consolidate. Cf3 syntax makes this a hairy proposition at best. But this is not really a problem...

saintaardvark: .@markburgess_osl ...because I should be thinking about this as documentation (which can be long) of the desired system state...

saintaardvark: .@markburgess_osl ...rather than code (where the drive is for efficiency and lack of duplication). Have I got that right? #sysadmin

markburgess_osl: @saintaardvark Documentation => focus on end state (like GPS), Code => focus on start state + directions. The journey is irrelevant.

markburgess_osl @saintaardvark Docs also improved by seeing themes and patterns. That is still WHAT not HOW. So no contradiction.

So putting this in practical (can't resist the temptation to say "less Yoda-like") terms: what I think he's saying is, don't worry about code duplication or getting clever; you're documenting desired system state, and it's okay to be verbose.

Using the example I started with, it's okay to have NTP settings in multiple places (because SuSE needs two files, Solaris 1, etc). The coder in me wants to clean those up because it's all NTP, but the documentationist ("writers", I think they're called) relaxes and says "Can't have too much documentation." Which is fair.

But then I worry about having Multiple Sources of Truth(tm). The advantage of the first setup is that when I change the NTP server, it's ALL in one place; in the second setup, I have to remember: did I change it for SuSE? Solaris? CentOS? I've learned the hard way to be wary of such setups. I nearly always miss something; that's why I'm aggressive about consolidating.

I'm still mulling all this over.