Follow us...

The Case for Master Documentation

Ray Engleberg, Business Analyst, New Jersey Chapter

You’ve just completed the analysis for that high-visibility initiative. You have sign-off on the Requirements Package. You breathe a sigh of relief. Your hard work has paid off and you’re looking at some downtime.

What now?

This is a good opportunity to update your Master Document for any impacted applications. If you don’t have a Master Document, now is an excellent opportunity to begin creating one.

Master Documentation is the current and complete description of a system or application and its components.  It serves as a reference tool for the current state of the system as well as a benchmark for future development efforts.  Master Documentation is a living product; it must be updated anytime there is a change to existing functionality.

Disclaimer:  The components described in this article have been deemed appropriate for those Master Documents that I’ve maintained in my career as a Business Systems Analyst.  In creating your own Master Documentation, you may determine that some of the components described herein are not applicable for your purposes while others, not mentioned, are.  Each Master Document is unique and, as such, will have its own unique set of components.
  • Context Diagram – The Context Diagram shows the system and the external entities that interact with it. Its purpose is to define the scope of the system. Because the scope may change (i.e. – new flows or external entities may be added; existing ones may be removed or revised), it is important that the Master Context Diagram be reviewed frequently and adjusted as needed. 
  • Glossary – Any terms, abbreviations, and acronyms germane to the subject matter of your Master Document should be explained in this section. An alternate approach is to provide a link to a separate Master Glossary which includes terminology pertinent to multiple applications within the enterprise. 
  • Process Flows
    • Business Process Diagrams (BPDs) using Business Processing Modeling Notation (BPMN) have become the industry standard to graphically portray business activities (i.e. how work is performed) at a both a high and a detailed level. They also depict :
      • Actors / roles responsible for each activity (via lanes), and business entities (via pools).   
      •  The sequence of tasks. 
      •  Decision points plus alternative and parallel flows.   
      •  Triggers to tasks as well as responses, in the form of message flows between functional areas, actors, or roles and the tasks with which they interact.   
      •  Processes and sub-processes. 
      •  Artifacts, (i.e. sources of data) used by one or more tasks in the process.   

It’s important to name each task in the BPMN diagrams uniquely. This naming convention consists of a numeric prefix followed by a verb + noun phrase.  Examples:  1.0 – Identify Customer Account, 2.0 – Delete Customer Account, etc.  It provides for unambiguous task notation as well as ease in cross-referencing to other areas in the Master Document.

  • Process Descriptions – In your Master Document, each task in the BPD should be complemented by a textual description of that task. This approach is valuable for two reasons:
    • The Master Document is a living document, constantly being updated. Over time, subtle revisions to tasks occur, which may not be readily apparent in the BPD.  Notations within a BPD are helpful, but unless used sparingly, they can render the diagram unreadable. For this reason, a detailed description of each task is included. 
    •  Master Documentation is a reference tool, not only for BAs, but for Business Users, Developers, Architects, and other SMEs, each of whom has their own learning style. Some will gain understanding by viewing a diagram, others by reading full descriptions, still others by a combination of the two. By providing both in your Master Documentation, you ensure that each learning style is supported.
  • Essential Business Processes – In Seven Steps To Mastering Business Analysis (Copyright ©2009 by B2T Training), Barbara A. Carkenord describes Essential Business Processes as core business activities which are described independently of how they are performed and which remain relatively constant over time.
    • Functional Decomposition – The functional area to be covered in your Master Document is broken down into smaller functions or processes. Once you’ve completed this task, you can decide which processes meet the aforementioned criteria for Essential Business Processes. 
    • Essential Process Description – Because these processes represent standard functionality and are unlikely to undergo major revisions, they are described in detail in the Master Document. They serve as baselines against which future development can be referenced.
  • Business Rules – If you’re dealing with a complex application, lumping all Business Rules into one list would be counter-productive. Instead, divide your application into categories (Initiate A Transaction, Update A Transaction, Cancel A Transaction, etc.). Each category has a relatively finite number of Business Rules pertaining to it. This makes for easy reference as well as adding new rules or updating existing ones. 
  • Cross-reference each Business Rule with the associated Essential Process(es). Also, identify each Business Rule by type (source:  B2T Training). These types include, but are not necessarily limited to:
    • Fact – a statement that connects terms into a business-relevant observation.
    • Mandatory Constraint – a statement that expresses an unconditional circumstance that must be true or not true for the business.
    • Guideline – a statement that expresses a warning about a circumstance that should be true or not true for the business, often accompanied by a warning message in software.
    • Computation – a statement that provides an algorithm for arriving at the value of a term.
    • Action Enabler – a statement that tests conditions and initiates another business event or activity.
    • Inference – a statement that tests conditions and establishes a new fact.
  • Activity Flow Diagram – This is a high-level flow chart of the steps that multiple business units and systems perform to complete an activity or process. It shows the order of steps needed to perform work as well as alternative flows and parallel flows along which work may progress. It is not necessary to identify the individual business units performing the work at each step; this can be done via BPMN diagrams and process descriptions explained above. You can use Activity Diagrams or BPDs in your Master Documentation or you can use both in conjunction with one another.


Activity Flow Diagrams may also be used in tandem with Use Cases identifying the actors and the progression of steps to complete the work.

  • Functional Requirements – When you’re working on a new initiative, your focus is on new requirements, unique to that initiative. If you’re versed in the application’s functionality within the scope of that initiative, you may instinctively know if a requirement is met by the current process. If not, you’ll go through a learning curve to discern between new and existing requirements.

 

Master Documentation helps to ease that learning curve. By having current Functional Requirements documented, you’ll save time trying to decide what should be included in any documentation written against future initiatives. 

Make sure each Functional Requirement is cross-referenced with the appropriate supporting Business Rule(s).

Functional Requirements, like Business Rules should be divided into categories to allow for straightforward maintenance and reference. The principles for categorizing Functional Requirements are the same as those as described for Business Rules.

  • Non-Functional Requirements – These describe the necessary qualities, rather than the behavior and functionality of a system or application. They too can be divided into categories and identified by type (source:  BABOK® Guide, version 2.0, Copyright ©2005, 2006, 2008, 2009) including, but not necessarily limited to:
    • Reliability 
    • Performance Efficiency 
    • Operability 
    • Security 
    • Compatibility 
    • Maintainability 
    • Transferability
To summarize, the advantages of Master Documentation are as follows:
  • Everything Is Centralized. Prior to the creation of your Master Documentation, anytime a stakeholder had a question, it might have been necessary to review multiple existing documents or to check with a knowledgeable SME who may not be readily available. With one Master Document in place, anything anyone wants to know about a particular application is located in one place, easily accessible via a few simple “Find” commands. 
  • AS IS Analysis. Studying Master Documentation can assist in eliciting requirements by pinpointing aspects of the business germane to a current project as well as existing solutions.  Any relevant subject matter found in the Master should be verified with the appropriate SMEs.  This will aid in keeping the Master Documentation up-to-date and accurate. 
  • Reusability. Once requirements are implemented, those requirements plus any associated rules, processes, etc. don’t go away. Master Documentation can serve as a mini-repository for these items, allowing for their re-use in future development efforts. They can be located quickly, which enables you to focus your energy on new requirements, rules, etc. Of course, these will need to be incorporated into the Master once they are approved.
Master Documentation captures and stores information relevant to a system or application for long-term usage. As such, it is an invaluable tool for expediting impact analysis of new revisions by reducing analysis time and effort, maintaining prior solutions and supporting training.



Note: The author wishes to express his appreciation to Rose Scalabrini (Lead Business Analyst) who provided input and support for this article.