Daily Habits to Turn Your Git History Into Valuable Documentation

Your documentation doesn’t need an overhaul — your habits do

Mar 4, 2020 · 6 min read
Image for post
Image for post
A “why” doc in a Git commit message

As engineers, we write and commit code every day. Each line of code we introduce is just one small piece of a software system that’s likely to outlast the specific code we’re committing. Our goal isn’t only to ship the code today but to prepare the team to successfully add to and maintain the software system in the future.

Preparing the team for the future means making our code easy to understand by following best practices like descriptive variable names and encapsulating complexity. It also means making our software systems easy to understand by documenting the thought processes that led us to build the way we did.

In Part 1 of this series, we talked about how “why” docs reduce outages, save time, and empower our teams to build better.

In this post, we’ll cover how to incorporate “why” docs as part of your regular building routine using Git and Bytebase.

Image for post
Image for post
Daily Git practices for moving fast with confidence and empathy

Choose a Standardized Format for Git Commit Messages

When teams don’t follow a standard format in their Git commit messages, they’re demonstrating they don’t care about their Git history.

The Git history below only has work-in-progress commits. It doesn’t have anything descriptive about the changes we made or why.

Image for post
Image for post
How you don’t want your history to look

Engineers will often forego adding valuable information in their commit messages. This loss will cost time and frustration later when trying to understand past development.

Setting and abiding by a standard is the first step in signaling to your team that Git histories are valuable.

The broken-windows theory

The broken-windows theory in criminology says that”

“If a window in a building is broken and is left unrepaired, all the rest of the windows will soon be broken.”— via The Atlantic

By leaving a window broken, building owners communicate they don’t care about the building. As a result, the building is likely to fall victim to additional vandalism and crime.

If instead, building owners promptly fix a broken window, they communicate they do care about the building — and so should residents.

Fix broken windows in Git commit messages.

We apply the broken-window theory to our Git commit messages by requiring that messages always follow a standardized format. This sets the expectation that Git histories should be invested in and cared for.

We recommend each message starts with a verb, in the present tense, and ends in a period.

Image for post
Image for post
Git commit message following standards

Tip: Update your latest Git commit message with the command git commit — amend.Update any commit message with git rebase -i HEAD~n.

— via GitHub

Image for post
Image for post
Interface for amending existing Git commit messages.

Capture “Why” in Your Git Commits

Your code tells other engineers how your code works. But it’s also valuable for engineers to understand why your code works this way. A Git commit message is a great place to document a specific constraint at a certain moment in time because it’s available with the lines of code it directly impacts.

Attaching “why” to your code empowers your team with confidence and empathy.


In Part 1 of this series, we explored how insufficient knowledge can result in blind adoption. The fable of the girl and the fish illustrates the consequences of not capturing “why.” In the fable, a family blindly passes down a recipe from generation to generation without adapting when the initial constraints no longer hold.

By capturing “why” in your commits, including the constraints that impacted your work, you can help future engineers make better choices. “Why” docs give future engineers insights into your building process. With this stronger understanding of the software system, future engineers can have more confidence as they build.


Capturing the “why” in your commits creates empathy within your team.

“[Good docs] create an environment where people feel guided and safe when changing the software, especially the newer members of the team.”

— Birgitta Böckeler via ThoughtWorks

By capturing nonobvious thought processes that go into your work, you create an environment that encourages asking questions, not toiling away in isolation. You set an expectation for the amount of context engineers should have when they’re building so they’re empowered to ask for more information when it’s missing.

The “why” commit message

To provide your teammates with the context they need for your code, consider the following questions when writing your commit message:

“What constraints were present at the time of coding?

What other ways did I consider?

If I were reading this in a few months/years, what would I want to know?”

— Greggory Rothmeier via RubyConf 2018

Capture the Higher-Level “Why” in Git Pull Requests

Git commit messages are a great place for capturing the “why” that directly relates to a short piece of code. But a feature is usually not just one commit.

Each feature tends to include a set of commits, combined into one or more pull requests from a branch. The feature implementation has its own set of assumptions and its own “why.”

We like to capture this higher-level “why” in the pull-request description.

At Bytebase, our PR description includes:

  • What changed
  • Any constraints that impacted our work
  • Related trade-offs we’re accepting
  • Any next steps to do in this thread of work
  • What you tested manually
  • Screenshots if the UI is impacted
  • Any questions for the reviewer

Organizing “Why” Beyond Git

Git commit messages and pull-request descriptions are a great way to add “why” close to the code it describes.

Sometimes we need to understand “why” at an even higher level. For example, I might have the question — Why did we decide to use NoSQL for this project instead of SQL?

In this case, the “why” is best captured at the project level. This is the type of use case we built Bytebase for.

Bytebase is a web app for collaborative notes, where each note is a short byte. For each project-level “why,” you can create a byte in Bytebase:

Image for post
Image for post
A byte that captures “why” for using a NoSQL store

You can then add each byte to relevant collections, like “Decisions,” to make them easy to find later.

Image for post
Image for post
Decisions and “why” captured in Bytebase

And you can view different subsets of your bytes that are most relevant to you. Below, we’re looking at all of the bytes we’ve stored that relate to NoSQL.

Image for post
Image for post
All context for NoSQL from across our workspace

You don’t need an overhaul.

We repeatedly hear from engineers they need to embark on an initiative to overhaul their docs. We agree docs are essential to team collaboration, but we’ve found the solution tends to be simpler than teams expect. Just as in our personal lives, the most effective changes are small habit changes, not overhauls — the same is true of our docs.

By adopting a small habit of regularly documenting “why” in Git and in Bytebase, your team can achieve better collaboration that lasts.

Better Programming

Advice for programmers.

Sign up for The Best of Better Programming

By Better Programming

A weekly newsletter sent every Friday with the best articles we published that week. Code tutorials, advice, career opportunities, and more! Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Thanks to Zack Shapiro


Written by


This is the official blog of https://bytebase.io— the fastest way to write, organize, and collaborate on notes.

Better Programming

Advice for programmers.


Written by


This is the official blog of https://bytebase.io— the fastest way to write, organize, and collaborate on notes.

Better Programming

Advice for programmers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store