Deploying Effective Analysis

Effective Analysis is based on three main pillars. In Part II, we introduced the theoretical principles and techniques which help to keep the analysis and documentation outputs simple to read and easy to maintain. Part III was dedicated to concrete tools that enable the implementation of these principles and which help automate the repetitive manual tasks. In this chapter, we are going to elaborate on how to deploy the concepts and tools in the organization.

Each company has its existing systems, products, processes, or running projects. If the goal is to start doing analysis and documentation differently, it is not possible to just take the old stuff and throw it away. The transformation needs to be planned carefully and take the legacy assets into account. Also, it cannot be done as a big bang and must be done in increments not to affect the day-to-day operation of the company.

The solution to a big mess of documentation isn't a big rewrite but changing your documentation habits, so every small change turns the tide and leaves the knowledge base better every time.

– inspired by this tweet

The goal of this chapter is not to provide a comprehensive manual of how to implement the Effective Analysis. Actually, there is not a single, universally applicable approach. Thus, we are going to provide only the key milestones on which the concrete migration process could be based on.

Since the deployment process is very likely to differ significantly for corporations and software vendor companies, we describe the processes separately.

Corporation

The knowledge base in a corporation consists of specifications describing various organizational components, such as information systems, processes, products, or organizational structure. The particular order of transferring these components into the new knowledge base depends on the needs and priorities of the company. The following process outlines one possible way.

Phase 1: IT Systems

Even though information systems are just a tool to achieve business goals, they represent an important organizational component as nearly all of the nowaday's business processes are more or less dependent on IT systems. The knowledge of the systems is hence critical for any analyst who aspires to come up with the best solutions to business problems.

For this reason, the first phase focuses on mapping the information systems assets, identifying how the individual systems support business processes and what relationships exist between the systems. The goal is to create a core systems overview to understand what systems are powering the organization and how they are interconnected.

For bigger companies, this may represent a nontrivial task since a corporation might operate dozens of systems and applications. The good news is, there is always somebody who knows the system, typically an application specialist, a senior developer, or even an external vendor. They can provide the team with a brief description stating the purpose of the system, its main features, and integrations. Such description should not take much time for somebody who works with the system on daily basis and since each system is typically operated by different team, this activity could be carried out in parallel.

Steps:

1. For each system or application create an element in the CASE repository
2. Map the element to the Application component using the middleware
   • This automatically creates a skeleton of the system documentation
3. If the system has existing documentation, attach it to the generated overview page or insert a link if it's available through a URL
4. Create a basic context diagram to depict how the system interacts with the external entities
   • Use business language, avoid implementation details such as naming the concrete service calls for example
5. Incrementally start building the IT architecture part of the knowledge base
6. If the system is composed of multiple logical modules, repeat step 2 for each module

After finishing phase 1, the company will have a solid understanding of its systems and the relationships which exist between them. Additionally, storing each system in the repository will allow the company to start modeling systems changes in Enterprise Architect, trace the changes, and thanks to the easy-to-access wiki documentation, it can start gathering instant feedback from everybody in the organization.

Phase 2: Business Domains

While analysts need to understand the IT capabilities of the organization, the critical characteristic of a great analyst is the knowledge of the business domain. Although there are analysts who have spent their entire career working in one industry area and have basically become subject matter experts, it is more common to see analysts come and go, switching not only companies but also the domains. This implies that they cannot be effective from day one, as they first need to learn the domain. Training each newcomer individually requires the time and effort which could have been spent more wisely if the company had a guidebook introducing the domain.

But it is not just about training new people who joined the project. In the big corporations, we often see multiple concurrent projects all mapping the same domain over and over again. This costs a lot of money which could be saved if there was a common quality knowledge base. Creating an overview of each business domain within the company, including the business language, domain model, business rules, and business processes, have a positive impact not only on onboarding new people but also on future projects.

Steps:

1. Identify the core business domains within the company and optionally visualize the relationships between them
2. Cooperate with the domain experts (subject-matter experts) and create a high-level overview of each domain (or delegate it to the experts entirely). The overview should contain:
   • Domain introduction
   • Its role within the organization, how it is related to customer benefits
   • Business glossary
3. Map the core business processes in the domain
   • Mapping the processes to IT systems which support them
   • Mapping process inputs and outputs in the form of artifacts
     For example, documents generated by the systems, documents received from the clients, reports provided to the government/parent company, etc.

The more you manage to delegate to business people, the better, but keep in mind that although business people have the business knowledge, they are not good at structuring information and also do not have the required modeling skills. Also, do not expect them to tell you everything. This phase is mostly about gathering information from various people, aggregating it with available resources, and organizing it properly.

Phase 3: System Integrations

The system integration phase follows on from what has been initiated in phase 1. The first phase is mapping the systems operated by the company along with the main connections which exist between them. This phase continues with that but goes a bit more into detail and describes real integrations - interfaces, services, and data exchange.

Unlike phase 1 and phase 2, which both require the analyst to actually go and get the information from somebody, in this phase, there is a big chance that the information could be obtained automatically. The services and data files are very likely to be implemented in technologies that allow exporting. It is then easy to import them into the CASE repository.

Steps:

1. For each system, identify the core services and data flows coming from or to the system
2. Model the identified entities in CASE (preferably automatically)
3. Model the relationship between the systems and the identified entities to capture the integrations

Phase 4: Continuous Documentation Development

The previous phases are typically conducted by a team of trained people who create foundations of the knowledge base. But the purpose of the knowledge base is to allow anybody to contribute to it, so the continuous documentation development must be started up. This requires training people to model organizational components and teach them to document every solution immediately after release. This means that each project needs to allocate time not only to implement the solution but also to incorporate the changes into the knowledge base. This way, the current state of the enterprise is kept up to date.

SW Vendor

In the case of a software vendor, the situation is a lot easier compared to large corporations. Software vendors do not build enterprise documentation; they document only what is needed to implement and maintain a particular product. The advantage is that all information is accumulated around the teams developing particular products. This streamlines the process as it is not needed to talk to dozens of people to create foundations of the knowledge base.

Step 1: Map all active projects and products and set them up in the knowledge base

Step 2: Describe all business domains in which the SW company operates (the same way it is done for corporations).
This is to avoid duplicated domain descriptions created by different teams working on projects within the same domain.

If the products are from different domains, not sharing any common functionality and not communicating with each other, the knowledge base will be basically composed of a set of independent products. The situation is then easier because the documentation is basically created by the product team for the product team, and the demand for quality is not as high as in the case of the corporate knowledge base.

Step 3: Train the product teams and ask them to start converting their old solution documentations to the new knowledge base