Towards a single source of truth

I’ve come to realize that with complexity comes a large hit to the velocity at which one can develop software. Minimizing complexities when it comes to documentation and code discovery happens to be, in my experience, critical to a team being successful when programming anything with significant lines of code.

A pattern that has served me well to overcome this within a team is to always keep a Single Source of Truth (SSOT). A SSOT will give a team, for instance, a single place to find or create any documentation. If it is complicated or time consuming in any way, documentation will be out of date or non-existent. If the documentation lives in a place that allows for many unlinked and non-versioned files, then expect a very large hurdle for anyone attempting to use or update it. I believe that many open-source tools benefit from embedding the documentation into the code and using the associated ‘markdown-like’ technologies greatly due to this effect.

An SSOT can allow a lower barrier to entry to the codebase. Take the package.json that many web based teams have accepted over the last 5+ years. This is a SSOT for many things including the name of the software, its version and what packages it depends on. It can also have the correct way to test, share, update, run, build, etcetera, all clearly defined within the one convenient file. This may also be why many are choosing NPM scripts over [insert build tool of choice here].

Another SSOT is having a state within the application like redux (or countless others). Driving the user interfaces in a one-way direction, read only manner allows for much simpler logic in all the right places.

When working in code, look to minimize the sources of truth and the work being done will suddenly become much easier to manage and enjoy.