Unified Knowledge Base

In large organizations, documentation is typically not created by a single entity. Various parties create and consume documentation, and unfortunately, these parties usually do not collaborate with one another. They produce their own specifications, even though these specifications describe the same aspects. As a result, multiple descriptions of the same thing are created, they often overlap, and worse still, they frequently duplicate one another.

Instead of creating multiple versions of the same information, effective documentation promotes establishing a single repository that contains all available information about each organizational component across the organization. We call this concept the Unified Knowledge Base.

This concept is based on the fact that any individual, whether an enterprise architect, business analyst, or developer, needs access to the same information about how the organization functions. They all need to understand the organization's mission, goals, components, and functions in order to be effective in identifying and implementing solutions.

I became a much more effective technologist once I learned how the business actually works.

– @jon_moore

Practically speaking, each organizational component should be described in business terms, including its purpose, main functions, and relationships with other components, so that anyone within the organization can understand the component's purpose and business context.
What may be surprising is that the unified knowledge base is expected to provide information about the enterprise not only to implementation teams but also to business stakeholders. Business stakeholders need access to the same documentation used by the development team so they can review it directly and identify mistakes.

Knowledge Base Characteristics

The unified knowledge base is a repository containing all knowledge about the enterprise, including its capabilities, structure, products, processes, rules, and IT systems. The specific technology used to power the repository is not particularly important; what matters is that the repository fulfills several requirements necessary to meet the expectations of high-quality documentation described in the previous chapters:

1. Public and easily accessible
   • This is not how stakeholders should access the documentation:
     
2. Easily editable
   • If stakeholders are expected to actively participate in maintaining the documentation, it must be easy for them to edit.
3. Easy to reference
   • Individual parts of the documentation should be easy to reference, for example through URLs. This enables sharing and collaboration instead of copy-pasting and duplication.
4. Audit and versioning
   • If the documentation is open to modification by “anyone,” it must be clear who made each change and when—it must be possible to audit changes and revert them.
5. Searchability
   • Since the repository contains a large amount of diverse information, it must be easy to search. The good news is that having everything in one place allows users to search it with a single query.
6. Unified content
   • All components are documented in a consistent manner and share the same attributes, making it easy to move between specifications since they look similar and maintain the same level of quality.

In the following section, we discuss various approaches to managing the knowledge base, including a reference implementation that illustrates how to apply the concept using available tools.