Since early 2019, we've spoken to dozens of teams that manage business applications, such as Salesforce or NetSuite, and one of the most prevalent pains we heard about was around documenting changes.

We believe that we have a valuable solution to offer. In this post we'll cover our understanding of the key challenges with documentation, our suggestion to replace documents with Git, and the reasons why we believe this to be a better approach that will benefit you and your team.

Let's dive in!

‍

What's wrong with documentation today?

Documentation is great, and even necessary, as it helps us maintain order and a clear history, especially for compliance purposes. However, the common practice of relying on documents or spreadsheets has significant drawbacks:

• Discoverability - Many teams struggle with finding the right documents at the right time
• Relevance - The high pace of changes makes many teams fail at maintaining up-to-date documents
• Compliance - Figuring out who altered what, where (and why) is a major PITA in every audit

The key to a better future: Git.
‍

What's Git?

Git is a time machine for text files - You can travel back in time to snapshots you created called commits. A commit contains:

#1. Text differences in the text that were done following the previous commit

#2. Creation timestamp and author

#3. A message by the author

‍

We'll discuss the great value of these data points later.

The Git commit message is divided into two parts:

#1. The commit message subject - A single line describing the change in a way that'll capture the main gist, making it a breeze to Review a list of changes quickly.

#2. The commit message body - Free text where you can elaborate more on the change, allowing whoever reads the commit message in the future to drill down as needed.
‍

Git and Salto, a winning combo!

How it works

Salto turns your business applications' configuration into human-readable text files - the perfect content to manage with Git. Changes made to your business applications can be fetched with Salto, and saved to your Git repository as commits.

To create valuable documentation, all you need to do is write good commit messages. The rest is taken care of by either Git or Salto.

‍

Discoverability, now made easy

Finding the documentation you need takes two steps:

#1. Finding the right file

#2. Reviewing the file's commit history

Both steps are quick and simple. Salto's powerful search tools support finding the right file, while Salto's web app, GitHub, and many other apps provide tools for listing and understanding historical contexts using commit messages.

‍

Relevance, achieved with elegance

A commit message is, by definition, relevant to the change contents captured in it. Therefore, recent commits that affected the configuration you're looking into should be exactly what you need.

To cultivate relevance, we recommend using the 'why, what and how' approach:

• Why is the business context in which a change request was made. For example, a decision to change how sales regions are defined due to a recent re-org in the sales team
• What is the change explained in simple, legible terms. In this example, "we're splitting America up into NA and LATAM"
• How is the technical implementation - the specific configuration changes - required to support the decision. In this example, creating new sales regions in Salesforce, assigning specific people to those regions, etc.

Here is how it is going to be mapped in a single commit:

Subject:

‍What and Why - In the message, it's common to provide a short explanation of what the change was and link to a Jira issue or to any other artifact that explains why the change needed to happen.

Body:

‍How - The commit's captured content, including specific config changes, the files affected, etc.

‍

What's next?

We believe that versioning with Git is part of an exciting change happening throughout the business operations field, maturing and transforming the field using disciplines that have been proven successful in other fields. In a way, the business operations field transformation reminds us of the DevOps revolution that upgraded both the industry and countless careers.
‍

To summarize

By utilizing versioning with Git - as opposed to just documenting - you can easily improve your day-to-day workflow, add clarity when synchronizing teams, and keep your auditing compliance seamless.

So Git'on the versioning bus and start your journey towards the future now!