Judging "Right" from "Wrong"

 There is no “Right Answer”

In a Traditional Development Model – there is no single, authoritative description of what’s “right”.  If there’s a specification at the beginning of the process, that is authoritative to start out with, but the moment the developers start writing code, the Spec becomes secondary.  At the end of the day, if there is documentation, that hopefully says how the system actually works – but it’s not authoritative, stale and out of date, and frequently just wrong.

In a Traditional Development Model, the same notions/ideas are typically described again and again and again.  Even if multiple languages/platforms are not supported, even a small project might easily have 3 or 4 “copies” of each concept.

1. The Specification
2. The Code
3. The Tests
4. The Documentation

Then, if a change is needed, the process repeats itself.  First, a “Change Request” is created, then the code and unit tests are updated, and then, if there is time, the documentation might get updated as well.

Replication in “the Source Code”

Also, within “the code”, the same ideas are repeated over and over:

1. Interfaces
2. Data Classes
3. APIs
4. Persistence (DB/SQL/NoSql/Etc)
5. Testing
6. Helper Functions
7. etc.

This is before you even get to systems which support/include multiple languages:

1. Java/CSharp
2. SQL
3. JavaScript/TypeScript
4. Json
5. Python
6. etc.

At the end of the day, it’s not uncommon for even small projects to include a description of what a “Customer” or “Widget” is, 10 or more times throughout the code.

Lots of different “Right Answers”

So in a traditional development model – there are typically 3 or 4 ways of doing each thing.  The “database” does it one way, the API slightly differently, the front end differently still.  In this model, there is no “right way” – just different ways.

Introducing a Single Source of Truth

With a single source of truth, (i.e. One, Single, Authoritative, Machine Readable, Description of the problem) things work very differently.  Now, it’s easy to say if any code/documentation/test/api/etc is right or wrong.  Simply compare it to the SSoT.  If it matches, it’s right, if it doesn’t match it’s wrong – and should updated to match.

This is a really important benefit.  It brings a clarity that is simply unmatchable in a “traditional” model.

Spec/Code/Docs – All for 1 and 1 for All

With an SSoT, the Specification is really a report, about a system that already exists.  In other words, writing the specification involves first turning the SSoT into an English description of the technology at hand.

Being able to turn the SSoT into English is proof that the SSoT is sufficiently complete/sophisticated in it’s structure to accurately describe the technology.  If we can turn it into English, we should be able to use different tools to turn it into any language on the planet.

And since both the English Words, and the Code, and the System “Documentation” at the end of the day are all derived from the same, Single Source of Truth, they will all match each other – Because They are Not Source Code.   Instead, to start with, they are all derivative code.  Each derived from the same source.

Now – when the SSoT changes, everything in the repository all changes, as set.  The Specifications, the Code, The Tests, the Documentation, The APIs – All of “the plumbing”.  It all gets updated, together.

Most of what you think of as Source Code is actually completely derivative.

Speed, Price Quality - Pick All 3!

 

SSoT.me – the ‘Single Source of Truth’ Toolbox.

---

They say, “Fast, Good, Cheap… Pick 2” – but SSoT.me let’s you pick all three.

Creating software based on a Single Source of Truth allows you to do so in a fraction of the time time vs a “Traditional” development model. This speed translates into significantly reducing the overall cost of a project.

As a side affect benefit, this approach also results in dramatically better code along a variety of dimensions.

Us Humans

First and foremost though, Derivative Code can always “explain itself” in Natural Language English. This is the most important layer for all of us Humans!

This “Derivate Documentation” always (and this is important) matches “the tech” which it is describing, because is are is derived. Because is is not “source code”.

Derivative Code

“Derivative Code” is code derived from a Single Source of Truth or SSoT. When compared to code not developed with an authoritative SSoT, Derivative Code tends to be more:

1. Complete
2. Stable
3. Flexible
4. Durable
5. Understandible
6. Internally-consistent
7. And Responsive

The reason that the Derived Documentation always matches the tech it’s describing is that neither it, nore the derived-tech it is is describing is the “Source” description. Instead, both are “derivative code” – both from one, central, authoritative single source of truth. When the SSoT changes – both the documentation and the code change, because they are are derived, because they are not “source code”.

“Source Code” or “Hand Code”

“Source code” is expensive. “Source Code” has to be maintained by hand. Human Hands. And Human Hands are expensive.

The goal of ever project should be to reduce the total amount of source code, since 1,000,000 lines of source code will inevitably cost more to create, maintain, upgrade, manage, etc than a 1,000 line app all else being equal.

And one way to dramatically reduce the amount of “source code” which you have to manage is to turn 50, 60, even 90% or more of it into “Derivative Code”. What that means is that when the SSoT changes – 80% of the code in the project automatically updates itself to match the new design.

To be clear, the “source code” would still have to be updated “by hand”. So the remaining 20% of the changes needed would still need to be done by human beings – but hopefully “the interesting bits” in most cases. In other words….

What is the “Low Hanging Fruit?”

The 80% that is most likely to be turned into derived code first, is “the plumbing”. The … well … “derivative” … parts. i.e. The parts of the code that are not too interesting, and are primarily following a well established pattern. This includes any code which, if pointed to, is 1-of-n. Are there 2? Maybe it’s derivative. Are there 3? Or 10? Definitely derivative.

What we’ve found is that most developers are surprised at how much of the code in their project can be isolated and turned into derivative code.

Get Started >

SSoT.me Windows CLI

Currently the SSoT.me CLI is only available on windows.  We hope to port it to Python in the next few months, but for now, it’s Windows only.

Installing the CLI

Step 1. Go to https://explore.ssot.me/app/#!/home

Step 2. Click on

Step 3: Windows may see this as a unknown program…click see more and continue anyways.

Step 4:

Step 5: Click Next>Next until finished.

You should now see SSoT.me folder in your C:\Program File (x86)\ directory.

 

Step 6: Powershell

OPEN UP POWERSHELL: Search Powershell in the bottom left hand corner and open the program.

I would recommend pinning this to your taskbar by right clicking and pinning the program once it is open.

Now that you have powershell open you can navigate. For people who are new to powershell or linux commands just some basics to help get around folders.

Step 8: Navigate in Powershell (if you are familiar with basic folder navigation in powershell skip to step 9)

You can see in the image below that currently I am in the “C:\Users\me” this is based on what is after “PS” and what is before “>”

To switch folders or “Change Directory” you can use the command “cd”

So I could type “cd C:” ENTER and I would go to the C: folder on the computer.

If I type “ls” or “LS” ENTER I can see all the files and folders in my C:\ folder

 

Instead of typing out the full path of the folder I want to navigate to you can type cd and the folder name and if that folder is in your current directory you will navigate there. Notice if you type

“cd U” then TAB key it will fill in with something that looks like “.\Users\” if you hit enter you will see you are now in the users folders based on the text after the “PS” and before the “>” (See image above)

 

https://explore.ssot.me/app/#!/view1

 

If you don’t have a key you can use the test key for now.

{

“emailAddress”: “test+1@ssot.me”,

“secret”: “{this-value-is-emailed-to-you}”

}

 

Step 10: Edit ssotme.key file

Go ahead and open file explorer window and go to the folder we have created in Powershell:

RIGHT Click and edit in any text editor (I am using notepad++ but notepad will work as well)

 

Paste in the following text – you can replace the email and secret with your own information.

{

“emailAddress”: “test+1@ssot.me”,

“secret”: “{this-value-is-emailed-to-you}”

}

 

Don’t forget the curly braces seen on line 1 and 4. Your should be emailed to you shortly after you register.

 

Step 11: Next Steps

Now you should be ready to start one of the ssot.me tutorials

Check out:

Website: https://explore.ssot.me/app/#!/home

Github for tutorials and more: https://github.com/SSoTme

First Project tutorial: https://github.com/SSoTme/ssotme-ms-ionic-seed

What is A Single Source of Truth

 Overview

Development based on a Single Source of Truth is like creating Cross Platform Interfaces for your Technology.

And just like a Java or CSharp interface, a Single Source of Truth allows you to make decisions once, and then act on those decisions consistently across multiple platforms and environments.

In a traditional development model, the same notions/ideas/concepts are defined again and again, will little to no concern for duplication.

Development based on a Single Source of Truth

To effectively use SSoT.me to develop software, it is important to have a clear understand of what a single source of truth is.

A good single source of truth is a Description of Technology which is a:

1. Single
2. Authoritative
3. Machine Readable
4. Platform Agnostic
5. Queryable
6. Description of What is needed

Single

The most important aspect of a Single source of truth is that there is only one of them.  The most common mistake made in a “Traditional Development Model” is that the same notions are described again, and again, and again – and in each place we call that “Source Code”.

Authoritative

Many projects actually have development assets which would make good Single Sources of Truth, but they lack Authority.  In other words – after finding a good Single description of what is needed, the next KEY is designating that description authoritatively as “the” description.

Machine Readable

Another key aspect of developing an SSoT is that it must be machine readable.  Creating a single, one page picture of the technology is a fanstastic start.  But if that picture is embedded in a PNG that’s not as helpful as if it is in a simple JSon or Xml Description of a flow chart..

Platform Agnostic

SSoT’s which are easily read by Mobile, Desktop, Windows, Web, iOS, Android, Linux, etc are better than Single Sources of Truth which are targeted at a particular environment, language or technology.  Good examples of platform agnostic SSoT’s are:

• Json
• Xml
• Csv
• Xlsx
• DBs (Sql, Postgress, MySql, NoSql, etc)
• Google Docs/Sheets
• etc

 

Description of What is needed

A key aspect of a good Single Source of Truth is that it contain as many of “the decisions” that have been made as possible.  In other words, the SSoT is the perfect place for all of the tribal knowledge.  In other words, once you’ve created the SSoT, there should be no tribal knowledge.

Because anything that would ordinarily be treated as “tribal knowledge” should be written down!