Effective Analysis and Documentation

Application Component

An application component represents functional entities such as software applications, information systems, or their modules. It encapsulates its behaviour into functions and its data to data objects or data files. The functions could also be made available to the external application components through interfaces as exposed services. The application component could represent the entire application or its individual parts at all possible levels of detail. In other words, the application component may be a mobile application, a large information system, or just a small utility application. It can also be a logical part of the complex system. For example, Facebook Events is a logical module of the whole Facebook platform.

For the sake of simplicity, Effective Analysis works with three predefined application component levels: system, module, and submodule:

  • System A
    • Module 1
    • Module 2
      • Submodule I
      • Submodule II
    • Module 3
  • System B
  • System C

For example, a typical customer management system contains modules such as Accounts, Contacts, or Leads:

aa

Documenting Systems

Knowing what systems the company operates and how they interact with the other systems is a valuable asset. It is necessary for the effective design of the future solutions, for evaluating solution feasibility and for identifying future solution impacts to the current IT architecture. From the documentation's perspective, the same requirements apply to application components as to any other artifact: there should be a central register of all internal and external systems, and all application components should be just referenced from documents and not be duplicated.

Besides understanding the systems the company operates, it is also crucial to be aware of the external systems, whose services the internal systems use. The goal of the systems documentation is to describe the capabilities of all systems, both internal and external.

CORPORATION VS. SOFTWARE HOUSE

The need to document systems and applications portfolio is particularly important to corporations that operate dozens of systems. The situation is quite different for software vendor companies delivering solutions that integrate with their customers' systems. On the customer's side, systems are usually not appropriately documented, so to successfully integrate the systems, the vendor needs to create its own specifications of the customer's systems, especially their interfaces. It might then happen that multiple teams integrate with the same system, and they all document the same interfaces. For this reason, the software vendor company should centralize the knowledge of the customers' systems to prevent duplicated documentation efforts.

The following list provides examples of what is useful to include in the documentation of the system:

  1. Overview
    • A short summary of what is the business purpose of the system (why the company has it), its main business functions and responsibilities
  2. Context of the System
    • Describes the position of the system in relation to other entities
    • Usually depicted using context diagram
  3. Main Modules
    • Complex systems should be decomposed into smaller logical parts, modules or submodules
    • Each module/submodule should be documented the same way as it was a standalone system
  4. Interfaces and Services
    • Describe the services the system exposes through interfaces
  5. User Interface
    • The goal is not to describe every single input field in the application, but rather just the main screens, their business purpose and perhaps the transitions between them(screen flows)
  6. Outputs
    • List documents, reports, data files, etc. which the system generates