A single source of truth. This is one of the most used and most overloaded terms in model-based systems engineering – perhaps second only to “model” itself. A clear and compelling objective on the surface, it is shorthand representing an aspiration for project teams and a benefit of adopting MBSE. But not all “single sources of truth” are created equal. Nor do all projects have the same level of need.
As with “model,” it is worth clarifying the term to ensure accurate communication. Having a different definition of need or a different definition of goodness is not itself a problem. Believing that you are aligned – in need or in capability – when in reality you are not, is where the problem resides. In this spirit, we can recognize five capability levels for “a single source of truth” in systems engineering.
Level 0 – The Human Repository
Humans have long relied upon the tribal elder and storytelling for maintaining knowledge and passing it on from person to person. Only in the last 5,000 years has the written word complemented and slowly supplanted the human repository for the capture and maintenance of knowledge. Even today, on any project and in any organization, there remains a great deal of information that resides only in the minds of individuals. Data corruption (imperfect memory), data loss (the departure of team members), limited access (requiring contact with the individual), and drift (subtle changes in our understanding over time) – the challenges of the human repository are clear. For processes that are relatively simple and unchanging – hunting animals on the plains of the Serengeti, weaving fibers into rope – level 0 may be sufficient. But none of us would aspire to use the human repository for a modern single source of truth.
In acknowledging level 0 as a starting point, we should not overestimate our progress. Whether framed as tribal knowledge, implicit knowledge, or simply things that no one thought to write down, more knowledge still resides in the human repository than any of us would like to believe. A Delphi Group study found that more than 40% of knowledge in an organization is captured only in the minds of team members. And while the human mind may no longer be our sole repository, neither are our other repositories as complete and singular as we believe them to be.
Level 1 – The Document
The system specification document has long been the authoritative source of truth for systems engineering. In what we now refer to as document-centric systems engineering, if you had a question on the system requirements, you went to the document. If you had a question on the interface definition, you went to the document. A well-written document compliant with a good template allows the knowledge creator to record information and the knowledge consumer to locate the information of interest.
For systems that are rather simple and stable over time with neither the environment, requirements, nor implementation changing, the document has proven to be a very effective single source of truth. It is relatively easy to both author and read, requiring no special knowledge of notation nor tooling for creation or consumption. However, as is often the case, this strength is also a weakness. While the written word is flexible, it also lacks the precision necessary for high assurance communication. The translation from concept in the mind of the author to the written word to the exact same understanding in the mind of the reader is a journey marked by many minor errors unacceptable in complex or evolving situations.
Beyond communication issues of precision and alignment, the document as the single source of truth breaks down as the system scales upward in complexity, both detail and dynamic. As the detail complexity grows and the system has more and more interconnected parts, the document grows larger. Classically, a system is represented not by a single specification but by a library – requirements, interfaces, system and subsystem, test. Even if we refer to the library as a single source of truth, consistency of information across the documents is far from assured. In fact, just the opposite is more often the case. For any sufficiently complex system, we can guarantee inconsistency in the specification – either due to varied understandings if authored by multiple individuals or due to drift in understanding if authored by a single individual over time. Factor in dynamic complexity with changes in requirements and design, and the problems simply compound. Documents are coarse-grained representations of information poorly suited to knowledge management and evolution over time.
Level 2 – The Data Dictionary
The data dictionary moves us from representing knowledge as one coarse-grained artifact (a specification) to many fine-grained items (individual requirement statements, functions, performance characteristics, verification statements, and more.) Whether described as objects with properties or entities with attributes, the concept is the same. Rather than managing the document, we manage a repository of information that represents our system of interest. This repository (generally a database) becomes our authoritative single source of truth where the system specification is authored, modified, and maintained. In the model-based world, documents do not disappear. They become composite representations of information produced automatically from the data dictionary.
The concept of the data dictionary is neither new nor unique. It underpins requirements tools, SysML tools, project management tools, and even common office tools such as Microsoft Visio. By changing the granularity of information, leveraging databases, and applying basic data management techniques, we address many of the flaws of level 1. As the system grows in size, we simply add more objects to our database. When a requirement is changed or a component renamed, we simply update that information in one record rather than searching for all references throughout a document.
It is worth noting that the question of precision and accuracy of communication is not inherently addressed by the adoption of a data dictionary. A data dictionary is simply a mechanism for capturing the identified information – the objects of interest and the corresponding fields. The quality of communication is governed by the clarity and the quality of the data model itself (the metamodel or the schema.) Starting with a blank slate (an undefined metamodel) may appear to provide ultimate flexibility but requires the team to engineer both their system and their engineering taxonomy so that all concepts and terms are clearly defined. Beginning with an extensible systems engineering metamodel allows a team to leverage the insights and experience of prior projects as a starting point for their systems engineering language and then tailor the data dictionary to elicit, capture, and maintain the specific information of interest.
Level 3 – The Relationships
Within the MBSE world, most data dictionaries today stop at the point of capturing objects and their properties. This allows users to define requirements, define activities and items, define blocks, and reference them in many different places across our system design. However, it stops short of capturing a critical piece of information – the relationships between objects. And systems engineering is all about the relationships.
This is the first point where there is great confusion regarding “a single source of truth.” Many will challenge this notion, saying “I have captured not only my objects and properties, but also the relationships.” That may be true, but the question is: where have those relationships been captured? In an artifact, or at the data level?
If we consider for a moment a sequence diagram and an activity diagram for a specific process, a traditional data dictionary allows us to define a set of activities and messages that we can use across both diagrams. If we have chosen to draw the activity diagram first to show detailed behavior, we can then manually draw a sequence diagram of the same aspects highlighting the exchange of information between parts of our system. We do not have to recreate the specific activity objects, but we do have to recreate their relationships – first putting them on the diagram and then relating the items and messages. If we change the name of a given activity, it will change on both diagrams. But, if we remove an activity from one diagram or add a new message to another, the other diagram will not change. We must manually create and maintain both diagrams even though the information content is overlapping. In level 2, we may represent relationships, but we are not capturing them at the data level. We are representing them at the drawing level which means our single source of truth is incomplete.
Ensuring that our underlying repository captures objects, their properties, and their relationships is critical as we address greater complexity and an ever-accelerating pace of change. Managing the relationships as part of our single source of truth ensures consistency of this critical dimension of a systems specification so that not only is the definition of a given system message consistent, but also, one has a clear understanding of where that message is created and what that message triggers. As the number of artifacts (diagrams, documents, and more) increases, the project team cannot hope to maintain consistency of relationships across the various artifacts, and an inconsistent understanding of relationships will lead to system failure.
When defining the single source of truth, as one expands from a taxonomy of objects and their properties to also define the meaning of the relationships, one moves to an ontology that ensures a common representation and understanding of the system parts, characteristics, interrelationships, and interactions.
Level 4 – More than the Specification
The first four capability levels are defined by the mechanism and fidelity of the single source of truth. The fifth level deals with the scope. Are we only capturing the system specification? Or are we capturing and managing the greater set of information and interrelationships involved with successfully engineering the system of interest? This is the second point of confusion regarding “a single source of truth.”
SysML itself is tuned as a system design language enabling us to represent requirements, behavior, architecture, and the parametrics of our system. It includes basic mechanisms for rationale and comments, but the information involved in successfully executing systems engineering processes and engineering a system is far greater. What concerns have been encountered, what alternatives considered, what paths chosen, and which concerns remain open questions awaiting resolution? What are our risks (interface, schedule, cost, and technical), the corresponding mitigation statuses, and more? Concerns and risks impact design. Design decisions close some concerns, open others, and both mitigate and cause risk. These programmatic aspects are simply two examples of information tightly coupled to the system design itself.
A robust single source of truth for a systems engineering endeavor reflects the greater dynamics between the system of interest, the production system designing the system, and the environment into which the system will be deployed. It becomes the authoritative design history exposing the approaches, the analyses, and the greater interdependencies in conjunction with the specification itself.
The purpose in recognizing five capability levels for “a single source of truth” is not to argue that every project should operate at the highest levels. Effective systems engineering is value driven, founded on the same underlying principles but tailoring processes, methods, and tools to the problem, environment, and design context. In the same way, we should seek the capability level fit for our purpose given our needs. For situations that are relatively simple, static, precedented, and short-lived, lower capability levels may be appropriate. As we move outward on the radar plot to larger scale, more complex, more dynamic situations, our single source of truth must be more robust in order to deliver the support we demand.
Not all single sources of truth are created equal. Rather than settling for shorthand, assuming alignment in understanding, and hoping for “fitness for purpose,” let’s ask questions to ensure understanding and tailor the capability level for the situation at hand.