Truth

 Certain things are factual. They exist. 

We tend to represent things that exist in different ways. Our representations tend not to be true. 

This isn't always the case - some representations can be tied in certain ways to the absolute truth. Here are some examples of things that are tightly dependent on the truth, and some that aren't.

Let's start with code. Code is, by definition, the truth - what is written will happen. Sometimes code can be misleading though. Dirty, convoluted code can mislead us as to what is happening. We might interpret it in untruthful ways - there might be side effects we didn't notice, etc.

This is why it's important to write clear, expressive code.

Next up, we have documentation in code. Comments, docstrings, etc. These can be truthful - but certainly aren't the truth. There's a difference - and having a false piece of documentation can throw us off of our goal of quickly learning the truth when we are reading code. This can happen quite easily, since the code - the truth - can change, without the documentation following.

You might think we just need to have a standard where everyone documents properly. This can be a decision to make an effort to properly represent the truth - but it isn't a certainty.

So what about actual documentation? Confluence pages? Wikis? Well, these are far from true. They age even quicker than code comments. The reason for this is that the activity of documenting isn't coupled with the creating of the truth, as is code documentation. So this happens independently, for one. Secondly, we can easily have duplication of documentation, maintained to different degrees. This creates lies - a page that contains only a part of the truth isn't exactly the truth. A page that contains old information, isn't the truth. And this goes on. How do we solve this problem?

I've thought of a few mechanisms. First, when we can, we need to make the truth explain itself. Code should be clean. Diagrams should be generated by code, to capture as much of the truth as is possible. Documentation needs to be kept in one place and one place only. New information needs to be added to the existing (maintenance, not spawning). These are our tools to capture truth precisely.

A bit more on documentation - this isn't a new problem. Some suggest only documenting high level information, design decisions, etc. But this isn't always desirable - in the 340 sense, we would waste so much more time digging around for things should we abandon general documentation of problems - experience - knowledge that isn't exactly represented simply in code. We need to document, and we need to read documentation. So we need to make it a must to follow the rules.