Unified Knowledge Base

In large organizations, documentation is typically not created by just one entity. Various parties create and consume documentation, and unfortunately, these parties usually do not collaborate with each other. They produce their own specifications, although these specifications describe the same aspects. As a result, multiple descriptions of the same thing are being created, they usually overlap, and what is worse, they often duplicate each other.

Instead of creating multiple versions of the same information, effective documentation promotes setting up single storage, which includes 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, be it an enterprise architect, business analyst, or developer needs access to the same information regarding the functioning of the organization. They all need to understand the mission of the organization, its goals, components, and functions to be effective in searching 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 language, including its purpose, main functions, and relationships to other components, so that any entity within the organization could learn the purpose and business description of the component.
What might be surprising is that the unified knowledge base is expected to provide information about the enterprise not only to the implementation teams but to business people also. Business people need to have access to the same documentation, which is used by the development team so that they could review it instantly and spot mistakes.

Knowledge Base Characteristics

The unified knowledge base is a repository containing all knowledge about the enterprise, such as its capabilities, structure, products, processes, rules, and IT systems. It is actually not important what technology is used for powering the repository, it is only required for the repository to fulfill several requirements to meet the expectations of 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 the stakeholders are expected to actively participate in maintaining the documentation, it must be easy for them to edit it
3. Easy to reference
   • Individual parts of the documentation should be easy to reference, for example, by URL. This allows sharing and collaboration instead of copy-pasting and duplication.
4. Audit and versioning
   • If the documentation is open to be modified by “anybody”, it must be clear who made the change and when - it must be possible to audit changes and revert them.
5. Searching
   • Since the repository contains a large amount of various information, it must be easily searchable. The good news is that having everything in one place allows searching with a single query.
6. Unified content
   • All components are documented similarly and share the same attributes so switching between the specifications is smooth as they look similar and have the same quality

In the following part, we are discussing various approaches to managing the knowledge base, including the reference implementation that illustrates how to apply the concept using the available tools.