Overviews - Drawing the Big Picture
The level of detail of the analytical outputs differs from project to project depending on the complexity, selected software development process, and other factors. Nevertheless, in all cases, the goal is to create concise and simple specifications, not to document every detail. The reason is that documenting details is time-consuming, in terms of both creating it and keeping it up to date. In addition, people usually do not need over-detailed specifications. What would you rather have? A quick high-level summary introducing the most important aspects? Or a comprehensive 100-page-long document that may be inaccurate and outdated?
In Effective Analysis, such a summary is called an overview. It could describe any component such as a business area, a business process, IT architecture, a concrete IT system, or just a single system component, for example. The goal is to help readers familiarize themselves with the subject matter by providing only the necessary summary information without going into details. The overview is a "landing page" from where the reader is referred to more detailed specifications, or it can represent the whole documentation.
The Actual Benefits Of The Overviews
They Describe General Concepts When learning new knowledge, the common approach is to start with the basics. It is especially important for analysts who must become business partners very quickly, so they must have something from where they could quickly learn the elementary facts, relationships and terminology without bothering with details.
It is not Easy to Get the Big Picture It is a paradox, that describing the thing with all the details is easier than assembling the big picture. Getting the big picture usually involves putting together various information from multiple parties, combining it and deciding what is important and what is already too detailed. It is hence a very good idea to create an overview at the time the team has access to all relevant parties, and the information is "fresh".
They are Relatively Stable Since overviews contain just high-level concepts that are relatively stable and are not prone to changing often, it is then quite safe to create them. It is a win-win situation. The overview includes information that is not easy to find and the information does not change frequently. So why not capture it?
Typical Overviews
Following list presents typical components for which it is usually beneficial to create overviews as they are mostly complex to be understood in detail right in the beginning:
- Systems - IT systems are complex entities which must be described in layers, so describing them means creating multiple views, both horizontal and vertical. This implies that the overview must look at it from different points of view too. The most important part is a description of its purpose, why the organization needs it, and what is its business value. After this is clearly described, the overview can continue with describing its main use cases, processes, data flows, and integrations with other systems. From the data perspective, it is also good to know which core business entities the system manages.
- Processes - The process overview should contain the purpose of the process, the main roles, IT systems involved, and the high-level model. The process is typically represented by a process diagram and the overviews typically include only the highest-level (L1) model.
- Business Domains - High-level overview of the business architecture and its components is especially important for new business analysts who need to quickly get familiar with the new business domain and it also helps fix the scope of the area and the basic terminology
- Projects - It is beneficial for people in the organization to know about the principal ongoing projects to prevent inter-project impacts or project clashes. On the other hand, to discover the mentioned problems, it is not needed to know the details, and this is exactly the use case for an overview.
Summary
- Overviews are great, use them. People will appreciate it, it will not cost you much effort, and since overviews are concise, it will be easy for anybody to maintain them.
- If you have reasons not to document things, write at least a short overview describing the particular project, process, or system from the high-level. People will thank you one day.
- If you are going to document something, create an overview first, and then add details. People do not like long specifications, they do not trust them as they are often outdated, so they first need to learn the basics anyway.