As a company grows, it is common for the Software Engineering team to grow up as well. And as the team grows, the documentation grows up too (or I hope so). Diagrams, RFC’s, setups, business decisions and every kind of record starts to become more important to every single engineer that enters or exits the company.

At this point (and preferably, at the start of the company) it is important to set a Single Source of Truth, especially for the documentation. But first of all, what is a Single Source of Truth?

Single Source of Truth⌗

A Single Source of Truth (SSOT) is a technique about collecting data from several organizational systems and putting it in a centralized place. A SSOT is a state of being for a company’s data in that everything can be located through a single reference point rather than a system, tool, or strategy.

And why is it important?⌗

Storing the knowledge of your team at a unique place that is easy to find and contribute helps a lot as of not losing information and design decisions during the teams’ growth. Also, it can make the onboarding step easier, causing less of a need for synchronous meetings for knowledge transfer. Besides that, not having a unique place can carry out some legacy data that doesn’t matter the reality any more.

Imagine entering a new company and having to go person by person, squad by squad, asking where the documentation is or why something has been done in some way. Imagine having to enter in Jira, Miro, GitHub, Excalidraw, Trello, Google Drive (and more 27 other tools) just for checking something that could’ve been a Markdown file in some general engineering repo in GitHub.

What options do I have?⌗

Looking for the market, we have tons of options for documenting and storing data. It’s important to put in the table how easy it is to use and contribute, and how comfortable your coworkers are with the tool in question. Personally, I really like to use GitHub for engineering team behavior. And when I say use, I mean to use everything that the tool offers, not only the versioning part, but also the Projects, Wiki, Actions, etc.

In this post, we’ll focus on code versioning and the Projects feature of GitHub. With code versioning, you can store your documentation in some Markdown files (remember to use a common repo for this), versioning the information and guaranteeing the integrity of the documents. Also, with a Markdown structure, it’s easy to migrate to some other tool later, if you want. It’s valid to say that you can use GitHub Wiki to store this kind of data too.

When we think of diagrams, there are a couple tools that can help versioning them, letting diagrams work in the idea of Diagram as Code. Mermaid and Diagrams are some of the options.

Now, GitHub Projects is very useful as a tool to organize your workflow framework (Scrum, Kanban, Scrumban, etc). You can create issues that turn in cards and link PR with them. Issues are a great way of recording technical discussions. Also, you can automatize the status of the cards in the project with simple efforts. Sometime ago, I started in a project that was using GitHub Projects, but then moved to another tool due the lack of easy metrics gathering tools. Nowadays, it’s a native feature.

With that in mind, GitHub looks like a very complete tool for diverse aspects of the engineering day-by-day challenges.

TL;DR⌗

Focus on setting a single place to keep all the documentation of your company. Start with your engineering team, but bring it to the other department’s tables. Don’t bother overthinking about how to start, or what tool to use. Atlassian, Github, Azure, all of them offer good quality tools and resources to help you on this mission. Start from something and study the pros and cons during the process. You can move to another place quickly if you set-up a good start, using resources that allow this migration, like Markdown. The sooner you start, the better.