The source of truth for configuration is the configuration
REMEMBER THIS MIGHT TAKE YOU A WEEK TO WRITE AND GET RIGHT. OH AND THEN MAKE A VIDEO OUT OF IT.
AND IF YOUR FIRST TAKE DOESN'T FEEL RIGHT, SIT ON IT! FOR AS LONG AS YOU WANT.
Is it possible to over-document something? To record too much information about a thing? It is. Here's why that's a problem, and how to avoid it.
At last week's Small Business System (SBS) Zoom session, we were chatting to Daniel about recording the Internet accounts that one has.
You might be tempted to export this list of accounts from your password manager. You'd create an Excel spreadsheet, say, and now you can make it a nice table and count the rows and maybe do some grouping.
But what you've just done is to duplicate the canonical source. And as soon as you have a duplicate, you should worry that it will 'drift' from the source of truth.
It is invevitable that you'll create or delete an account and forget to update this spreadsheet.
A busy part of my own SBS is ID 14.32 External software & services. As a software company, I have a lot of those.
WhAT YOU WANT TO RECORD
- Is the stuff you can't look up.
- E.g. with your CLI, what's the release pattern? Which parts do you have to touch?
- THis is process not config.
Config
USE THIS AS SBS MINUTES IT MUST WANT YOU TO BE AT THE MEETING AND MAKE YOU FEEL LIKE IT IS OKAY IF YOU MISSED IT
It can be a good idea to record 'configuration' in your JDex. Let's use the example from last week's Small Business meeting: a Decimal asked for advice about their various accounts
What's 'configuration'?
Simply put, it's the recording of how a thing is set up. That is, how it's configured.
Let's deconstruct these many accounts with a focus on their 'configuration'. Starting with the source, which is the account itself. Let's use your Johnny.Decimal account as our example.
Diagram: the account exists
Initially, there is the account itself. You created an account on my site. From my perspective, this is impossible to ignore: when I view the list of users in my console, there you are.
But from your perspective, this is easy to forget. You could create an account and, if you never recorded that fact, it would be easy to forget that you had. You might then accidentally create another.
Diagram.
In this situation, I have just the right amount of configuration regarding your account, and you don't have enough. Let's improve that.
Record that it exists
The most natural place to record that an account exists is in your password manager. So you do that, and now we're looking pretty sweet.
Diagram.
Stop there
Now, what can be tempting â and this was the question posed by our Decimal at the meeting â is to want another place to record these accounts. This is where you might create a spreadsheet so you can add extra columns and perhaps group things and add notes.
But this is a trap. Let's see the diagram for that first.
Diagram
The problem is that you have duplicated this data. T
The trick is identifying the single source of truth for this configuration, and stopping there.
If we think about where these accounts are recorded. First is the site. Disparate etc. second is our password manager. And third it can be tempting to use our JDex, or a spreadsheet.
But no. The role of our JDex is pointing us to our password manager. Telling us this is wheee it is.
My own business makes heavy use of 14.31, 2. At 14.31 I record the details of scripts and utilities that I create; at 14.32 the details of my implementations of external software like Discourse, the software that runs our forum.
There, it's tempting â I've done it â to record very specific details in my JDex. For the forum that might be specific lines of configuration.
To basically extract and make readable the exact settings. This is the behaviour to be avoided.
Counter: it can be useful to record WHY you recorded specific lines of config.
How I do it
Record existence. What do I have?
Record locations. Where even is a thing?
Record reasons. Why is it set up this way?
Record exceptions. Why is this one different?