Automated Dictionaries as Documentation Managers
The primary visible products of a system design are its narrative and graphic documentation. Some large projects produce large amounts of documentation, some of it running into hundreds of pages. Although most collections of design techniques (methodologies) provide some structure to the documentation, even the best methodology and the most meticulous designer or design team cannot organize, index, and cross index the information sufficiently to make it entirely useful. There are always needs to see the information in a manner differently from the way in which it is presented.
Additionally, even with the best organizing and indexing methods, paper documentation (documentation printed on paper) requires a great effort to revise and still more effort to maintain its currency.
In order to overcome these and other purely mechanical problems involved with producing and maintaining proper documentation, many firms rely on automated dictionaries or as they are alternately called, encyclopedias or repositories. These data processing system products are specifically designed to record, maintain and organize both analytic and design information, and come equipped with flexible facilities for producing a wide variety of reports on their contents.
Why a Dictionary?
Although automated dictionaries are usually discussed within the context of Data Administration, it is equally appropriate to discuss them in terms of documentation administration or documentation management. The reasons for this become obvious when one looks at what they are designed to do and what they are designed to contain.
These dictionaries are in reality application systems which have been designed to accumulate documentation. Although the majority of the documentation within them pertains to data, most of them also contain provisions for documenting the other components of the systems design environment: Entities, Relationships, Systems, Users, Reports, Forms, Functions, Processes, etc.
Most people do not look at them as systems, but rather as automated tools designed to contain business system design documentation. Dictionary system files, unlike most other business systems do not contain business transaction data or other business records, but rather they contain data and procedural documentation. This documentation describes and defines the components of the business 60 system design, and allows for each type of design component to be related to every other type of component, thus creating a powerful research, analytical and cross-reference tool.
Because of their automated nature, and their relative (compared to manually produced and maintained documentation) ease of updating and maintenance, dictionaries are the primary documentation tool for most business system design projects.
Because it is such an integral part of the design process, the function of documentation management should be carefully planned, not only with respect to the actual documentation to be captured, but also with respect to the roles, responsibilities, authorities and accountabilities associated with this new function
The following is a representative plan or charter for the documentation administration function:
Documentation Administration Plan
This plan shall cover the tasks and responsibilities of documentation administration and their effects on data strategy, data administration and data management.
The firm is embarking on a system (re)design program which will substantially change, rationalize and clarify the functional responsibilities and authorities and the operational activities of the firm and the data used to perform those operational activities.
II Sources of Documentation:
The products developed following the firm's System design methodology will generally follow a classification format where each successive product refines and provides further detail on the system components developed in the preceding products.
The tools used by the design teams must be capable of recording components from a very conceptual level down to a very detailed or physical implementation level.
Some of the tools (e.g. CASE products) contain internal documentation facilities which record product information as it is generated.
The design documentation recorded in the various dictionaries will reflect the products of the specific techniques used and will include, but not be limited to graphics, narratives, definitions of terms and components, and detailed element (implementation or physical level) definitions.
Since a classification approach has been adopted and since the design approach will further be separated into data products and functional products, and since these products will be developed concurrently, there is a need to tie components at each level not only to each other, but to those product components both above and below them in the design classification hierarchy.
III Documentation Management Approach:
The business system design models and accompanying narratives will generate voluminous amounts of information or design documentation.
This documentation can only be handled reasonably in an automated manner. The currently available automated mechanisms are the mainframe dictionary and the individual dictionary-like components of the automated design tools (CASE products) resident in the PC's.
The primary documentation management tool will be the mainframe resident dictionary.
To document all design components and establish full traceability and cross reference capability between all components.
To make automated documentation accessible to all users on a need to know basis.
To ensure that all documentation is logically integrated. that is, there is no redundancy or conflict of description or definition between design components.
To ensure free movement under appropriate control, of documentation items between PC and mainframe environments.
To ensure that there is a single accurate source of all final design documentation.
To ensure an efficient, easy to use mechanism for handling intermediate or draft product documentation items and maintaining separation from finalized approved items.
To ensure firmwide agreement or consensus as to the scope and detail of the documentation of each component.
To ensure an efficient data documentation gathering process
To ensure an efficient editorial review process for documentation items
To ensure an efficient mechanism for automating documentation and implementation thereof.
To ensure timely availability of automated documentation
To ensure timely maintenance of the automated documentation handling environment
To ensure periodic consistency checking of automated documentation
To ensure an efficient and authoritative mechanism for definitional conflict resolution.
Since the primary documentation elements in most dictionaries are the definitions of the items entered, the ability to generate clear and precise definitions is essential to an effective system design. The following represent a set of general rules that should be followed when creating any definition, followed by more specific rules for specific design components.
Generally speaking the general rules only reiterate rules of grammar and writing clarity. The specific component definition rules incorporate those general rules, provide questions which can guide the designer in creating a definition, and suggested standard format statements which should be used to begin each specific definition statement.
General rules for creating a definition
The following rules should be applied when creating the definition of any term, item or component:
The following are suggested rules and formats for creating the definitions of some of the major components of the design products, entities, relationships and functions. For best results, the rules for defining specific model components should conform to the following format:
The following are some suggested formats and rules for defining some common design model components.
Rules for defining and naming an identified entity
(name of entity) is unique, and descriptive of the distinguishing characteristics. It should be a noun or noun phrase. A noun phrase must have a noun and may include adjectives and participles. Prepositions may also be included for clarity.
NOTE: The name of an entity is a label for a set of data. Entities may be grouped in families. Unique labels are applied to the family as a whole, to groups of entities within the family, or to individual members of the family. Individual family members are distinguished by separate labels because they have different:
a distinguishing characteristic is a feature or property of the entity that sets it apart from its siblings. Siblings are entities that are children of the same parent.
The Classification model implementation
Because classification schemes are an integral part of the design process, the dictionary should have the capability to record the classification scheme itself. This can be accomplished through the use of a modification to the format for defining an entity. These modifications can be used to document the classification model for each entity family.
If used, the dictionary member type for an Entity would in effect be composed of a family of entry formats. Each entry format would describe a different type of entity alias, kind-of member or grouping in the classification model of the entity family.
To implement the classification structure five specific entry types should be used:
The following formatted statement should precede the statement listing the characteristics of the entity.
A(n) (name of entity) is a(n) (Base, Kind-of, Alias, Grouping, or Usage) entity.
Rules for naming and defining a function
>Rules for naming and defining a relationship
a) What are the names of the two entities which participate in this relationship?
b) What business rule(s) does this relationship represent?
a) Each (name of first entity) is (sometimes or always) (relationship) (one or many) (name of second entity).
b) Each (name of second entity) is (sometimes or always) (relationship) (one or many) (name of first entity).
The business rules which this relationship represents are:
The Dictionary Data Model
As with any collection of commonly used data, the design team should create a data model for the dictionary. Each entity in the data model represents a component of a product from the design process. This model should be accompanied by a brief definition of each entity in the data model, a description of that entity and the currently identified characteristics and relationships of the entity.
The following are suggested components:
Each unique occurrence of each design model component should be documented in the dictionary. The documentation of each occurrence should include, but not be restricted to, a definition of the individual component occurrence.
Most system design methodologies and CASE products are structured to produce the following minimum component documentation:
Although the contents of each dictionary entry type are dictated by the type of automated dictionary used and by the firm's documentation requirements, the following characteristics are strongly suggested to ensure proper documentation maintenance and traceability:
Data Directed System Design - A Professional's Guide
Written by Martin E. Modell
Copyright © 2007 Martin E. Modell
All rights reserved. Printed in the United States of America. Except as permitted under United States Copyright Act of 1976, no part of this publication may be reproduced or distributed in any form or by any means, or stored in a data base or retrieval system, without the prior written permission of the author.