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!

"Source Code" should not be "The Source" in 2013!

"Source Code" should not be the Source of an Enterprise Application's Infrastructure in 2013!

Instead, the infrastructure should be described abstractly, and then an ESCIM (Enterprise Source Code Infrastructure Management System) should maintain the application's infrastructural code.

This frees up software developers to focus on the "exceptional" cases.  The interesting cases.  The cases that provide an opportunity for creativity.  Cases that deviate from the established system architecture.

In other words - anything that can be automated, should be automated.  Let people do what people do best - be creative within an established system!   Or, easily and creatively manage/change the established system to make it better.

Developers are still slaves to infrastructure.  It does not have to be this way!

Software Design/Modification Should be considered a "Set Based" process

When Matt Cherwin, the skilled DBA at my company first joined, one of the first and best pieces of advice that he gave me was to think of SQL as a "Set Based" process.  In other words, something in our discussion had indicated that I was thinking about the specific rows in a table, and his advice was given in response to that observation.

Immediately - SQL became much "easier" to think about, manage and generally work with.

I have found that this advice also applies to software development.  I find that it is much more powerful to think about the entire system (as a set) and to think about changes to the entire system (set).  This heavily takes advantage of code refactoring - where essentially every single last change that is made to the code is done as a formal "refactor".

In other words, I'm going to refactor the code to...

• Rename the method x.Foo() to x.Bar();
• Add method X to Y in order to facilitate Z.
• Add 5 new properties to class Foo.
• Allow Bar's to be deleted.
• Create 3 overloaded version of method X.Foo() that allow for...

The point is that any one of these changes might modify 1 line, or 10,000.  It should not matter to me as the one implementing the change.  I need to understand the implications of the code change - but I should not need to actually eyeball each change made by "the system".  

I should be able to simply indicate what I want done - and a refactoring tool should actually make the changes to the code.  The more changes that can be made "as a set", the fewer bugs there will be in the final product.

Define "Set Operation": Any operation that can be completed as a single, atomic change in the IDE.

Find a cheap way to try!

I've spent a lot of time thinking about failure, and how the fear of failure so frequently prevents people from trying things.  Weeks or months can be spent debating the various ways that an idea might fail when a prototype could potentially be developed in days that would answer the question conclusively.

I recently watched a TED talk by Regina Dugan from DARPA - with a message about the amazing things that we can accomplish when we stop fearing failure.  One of the things that she kept mentioning, and it wasn't until this morning that I realized how important it was, was how little was known before a test, and how much additional knowledge was gained by trying - even when the attempt results in failure.

For example, when Chuck Yeager made the first Mach 1 flight - Mach 0.8 was apparently the best wind tunnel data available at that point.  Leaving the sheer courage necessary to climb into that cockpit aside for the moment, because he tried - they learned more about supersonic flight that day than in all of the previous testing/theoretical work that had been done up to that point ... combined.  

In example after example, she kept coming back to how much they learned the first time that they tried to fly Mach 20, or from the first prototype mechanical humming bird that they built (even though it only flew for seconds).  Trying, even if it results in what appears to be complete and total failure, almost always yields so much additional information about the problem being attempted, that failure can simply be categorized as an irrelevant side effect of the learning process.  Failing 10 times is fine with me, if those 10 failures lead to success - which lasts forever.