Automated Dictionaries as Documentation Managers

Introduction

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

Scope:

This plan shall cover the tasks and responsibilities of documentation administration and their effects on data strategy, data administration and data management.

I Introduction:

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.

IV Goal:

To document all design components and establish full traceability and cross reference capability between all components.

V Objectives:

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.

Definition rules

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:

1. All statements within a definition must be complete sentences.
2. All statements within a definition must be grammatically correct.
3. Circular statements are not permitted within a definition. A circular statement is one in which the term, item or component being defined is restated and used without qualifications or other explanation as the definition of the term being defined, e.g. A circular statement is a statement which is circular.
4. Definitions should use only objective and quantitative statements not qualitative or subjective statements.
5. Definitions must be free of ambiguity so that they cannot be subject to interpretation which may have the effect of changing the definition.
6. A definition must be capable of standing alone without the need for oral interpretation or explanation as to its meaning or intent.
7. Definitions must be free of organizational jargon, idiom or other terms which may be known only to insiders.
8. Acronyms may be used within a definition. On first use full English meaning must be spelled out followed by the acronym itself within parentheses, e.g. Computer Aided Software Engineering (CASE).
9. Each definition must be self contained and not dependent upon the existence or content of another definition.
10. Statements within a definition should not begin with a personal pronoun. e.g. It, They, His, Our, etc.
11. Definitions must place the term, item or component within a specific context or must state each occurrence of context where appropriate.
12. Definitions must contain at least one example or illustrations of an occurrence of the term, item or component being defined.
13. If the term, item or component, exactly as described, is known by multiple names or aliases, every alias must be listed within the definition.
14. If the definition of the term, item or component is unique within the firm, or is thought to be unique or markedly different from the generally accepted definition, it should be so stated within the definition.
15. A definition must contain a list of distinguishing characteristics:
    
    1. When the term, item or component must contain those distinguishing characteristics to be included in, or to conform to, the intent of the definition,
       or
    2. When such distinguishing characteristics are needed to gain a complete understanding of the term, item or component.
    
    
16. A definition may contain any statements necessary to convey an understanding of the term, item or component being defined, its context, its activities, its reason for existence or its reason for inclusion.
17. A definition may be as long or as short as is necessary to fully conform to the above rules, but should also be as concise as possible.

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:

1. Rule 1 should always be a set of one or more questions to which the content of the definition must respond
2. Where applicable, rule 2 should be the specific format to be followed when writing the first statements of the definition
3. Any additions or exceptions to the general rules for creating definitions follow item specific rules 1 and or 2.

The following are some suggested formats and rules for defining some common design model components.

Rules for defining and naming an identified entity

1. The definition of an entity must answer the following questions:
   1. Is it a person, place, thing, concept or event?

   2. What distinguishes this entity from all other entities?

2. The definition statements must follow the form:
   • a) A(n) (name of entity) is a (person, place, thing, concept or event) that (what it is, what it does and/or how it is used).
     where:

     (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.
     E.g.

     1. Paper
     2. Acid-free Paper
     3. Recycled Acid-free Paper
     4. Recycled Acid-free Paper for Archives

     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:

     • relationships, and/or
     • characteristics.
   • b) A(n) (name of entity) has the following distinguishing characteristics: (characteristic (1), characteristic (2), ... characteristic (n)).
     where:

     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:

• A Base entry format - incorporates every characteristic of any member of the entity family and every relationship enjoyed by any member of the entity family. The label of a Base entry is the only label that can be applied to any member of the family without exception. A Base entry cannot also be a Kind-of entry. There is only one Base entry per family.
• A Kind-of entry format - is used to hold the definition, relationships and characteristics peculiar to this kind of entity.
• An Alias entry format - is used to assign another label to another entry.
• A Grouping entry format - is used to assign a label to a group of entries which might otherwise have no explicit common parent but have a common distinguishing characteristic that yields the grouping name.
• A Usage entry format - is used to hold selected relationships and characteristics from one or more Kind-of or Base entry formats of the same family.

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.

where:
Base - incorporates every characteristic of any member of the entity family and every relationship enjoyed by any member of the entity family. The label of a Base entity is the only label that can be applied to any member of the family without exception. A Base entity cannot be a Kind-of another entity. There is only one Base entity per family.

Kind-of - is an individual family member.

Alias - is another label for an entity.

Grouping - is a label for a group of entities which otherwise have no explicit common parent, but have a common distinguishing characteristic that yields the grouping entity name.

Usage - is an entity with a set of relationships and characteristics selected from one or more members of the family.

Rules for naming and defining a function

1. The definition of a function must answer the following questions:
   a) What is (are) the purpose(s) of the named function?
   b) What are the major activities performed by this function?
   c) What are the major responsibilities and authorities delegated to this function?
   
2. The definition of a function should follow the following form:
   a) The function (name of function) exists for the following purpose(s):
   1) purpose (1)
   2) purpose (2)
   ...
   n) purpose (n).
   
   Where:
   (function name) may be a noun or noun phrase, but must not include the words function, process, procedure or activity or any variations of those words.

   b) The function (name of function) performs the following major activities:
   1) activity (1)
   2) activity (2)
   ...
   n) activity (n)

   c) The function (name of function) has been delegated the following responsibilities and authorities:
   1) responsibility (1)
   2) responsibility (2)
   ...
   n) responsibility (n)
   
   and
   
   1) authority (1)
   2) authority (2)
   ...
   n) authority (n)