Note: This was an “assignment” for TeamOps training, but thought I might as well post it here!
In small organizations, it’s generally easy to know what is the definitive source of truth since there aren’t that many places to look. Often, the source of truth is a particular document, or person. However, as organizations grow, different people or teams often remember or document the same things in different ways, and in different places. This is why it’s important to have a Single Source of Truth (SSoT).
Definition
In TeamOps, GitLab’s operating model, SSoT is defined as:
a virtual knowledge management system [with] all information data (policies, objectives, workflows, instructions, values, etc.),
and is an action tenet (behavior-based way of working) of the shared reality guiding principle.
Benefits
Having a SSoT means having only one version of an “artifact”, whether that’s a workflow, process, direction, or performance indicator. When something is written down and that source is always updated, then we can use it as a shared reference. This shared reference creates a shared reality, and hopefully, a shared understanding, and consistency across the organization.
When the SSoT is also public by default, then there doesn’t need to be different versions based on audience or permission, meaning less maintenance. It can also expand the shared reality to outside of the organizations, such as with partners and customers.
Medium agnostic
At GitLab, SSoT is a subvalue, and while we do our best to follow it, there is still some confusion about whether a single “thing”, such as a project, needs to have only a single source of truth.
Some of that confusion stems from the fact that we use a lot of tools. In every organization, you’re likely using multiple tools depending on the purpose. You have documents, slide decks, videos, and more. So how can you have a SSoT for something like a project?
TeamOps allows for the SSoT to be on different mediums, because it’s not the tooling that’s important, it’s (like much else) setting expectations and a shared understanding or shared reality that’s the most important.
“Multiple” SSoT segmentation
If we have artifacts on different mediums, it may seem difficult to keep to an SSoT. While information can live in multiple places, the key is to define the SSoT and refer to it whenever needed.
Slide decks and meeting agendas are dated to provide a snapshot of a topic. For example, for a project, a slide deck might be a status update, and the list of current priority, blockers, and risks. In the slide deck though, there should always be a link to where the work is being tracked. Similarly, in meeting agendas discussing a project, there should be a links to what needs to be kept up to date.
Different parts of a project might be tracked on different mediums or in different tools. For example, the overview and overall status could be tracked on a webpage, which links to a GitLab project, epic, or issue board to track specific work to be done. Each issue would then be the SSoT for that specific task or piece of work.
At GitLab, working groups are a good example of how the handbook page is considered the SSoT for an overview of what’s happening with the working group, but the specific pieces of work are in epics and issues.
So while on first glance, it may seem like there are multiple sources of truth, as long as it’s clear that the SSoT is segmented and in what way, there is a SSoT for each aspect of the project.
When you want to duplicate information
When multiple people or teams want to reference something, it’s common for people to want to copy or duplicate information. While there are certainly other methods, I want to cover common ways to provide the information people are looking for without duplicating it.
If you’d like a video version of the rest:
Embed or generate if you can
Following the Create Once Publish Everywhere model, when at all possible, generate or embed the content.
In cases where there’s a single data source, you can generate a version of the content you need. For example, GitLab has a list of product managers and all the counterparts in a single data file. The same data file is then used to generate different views of the same information, such as the Support Stable counterparts list and the Technical Writing Assignments list.
Other times, written content is not easy to generate, especially if the wording is important. In these cases, you might embed the content. You’re still using a single source, and displaying the information in multiple places.
Generally, you create a “stub” or section of a page which can then be generated to also be on other pages.
At GitLab, we use a website generator where “partials” can be included anywhere on the site. For example, the Manage stage introduction is a partial that is used on the Manage direction page.
Other times, the information resides in a different tool. Whenever possible, you can embed these too.
For example, GitLab frequently embeds charts for show the status of Key Performance Indicators (KPIs)](https://about.gitlab.com/company/kpis/), such as for Engineering KPIs.
Cross-reference and cross-link
When generating or embedding information isn’t possible, you want to cross-reference with a link. The purpose of links after all is to point readers elsewhere to find more information on what they’re reading about. Making use of links means we can add references to something where people are looking for it, and let them know where they can find the information. By making use of links, we can keep a single source of truth.
Regardless of the tooling you’re using, you are very likely to have a way to add a link regardless of it’s the same medium, or a different one.
GitLab’s product documentation is a great example of cross-referencing with a link instead of duplicating content. Just one example is the synchronization heading on the LDAP page, which leads users to an entirely separate page about LDAP synchronization.
Takeaway
The main takeaway here is to define the Single Source of Truth; make it clear when something is not the SSoT, to point to it; and do your very best to stick to it by not duplicating information.
It’s not always easy, but hopefully the examples I’ve provided give you ways to practice using an SSoT.
Thank you
As always, if you made it to the end, thank you!
Today’s picture is not a cute animal, but bread is often used in connection with success, and it looks like a turtle!
Learning (Lib)Tech 