Automated Dictionaries as Documentation Managers

Contact Martin Modell   Table of Contents


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


I Introduction:

II Sources of Documentation:

III Documentation Management Approach:

IV Goal:

V Objectives:

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,
    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).

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

        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)).

        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

  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).

        (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)


        1) authority (1)
        2) authority (2)
        n) authority (n)
>Rules for naming and defining a relationship

  1. The definition of a relationship must answer the following questions:

      a) What are the names of the two entities which participate in this relationship?

      b) What business rule(s) does this relationship represent?

  2. The definition of a relationship must be in the following form:

      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).

      (relationship) must be a valid verb form.

    The business rules which this relationship represents are:

      1) Business rule (1)
      2) Business rule (2)
      n) Business rule (n)

  3. Each relationship definition must be self contained and not dependent upon the existence or content of any other definitions other than those of the entities involved in the relationship, or existence condition statements.

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:

  1. Entity
  2. Relationship
  3. Characteristic
  4. Domain Element
  5. Context Element
  6. Function
  7. Keyword
  8. Process
  9. Activity
  10. Task or procedure

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:

  1. Component identification - the label of each occurrence of a component. e.g. Customer
  2. Component definition - the definition of each occurrence of a component, produced in conformance with the firm's rules and guidelines for creating definitions, specifying:
      a) what the component is
      b) what the occurrences of the component are
      c) what the component represents or includes, e.g. a customer is..., a customer includes...
  3. Component description - the rules and guidelines which determine the properties, attributes and traceability elements of the component, e.g. a customer is described by the following characteristics:...

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:

  1. The clear or standard English name of the occurrence
  2. The name of the occurrence as it is known and referenced in the dictionary (its dictionary entry key)
  3. A definition of the occurrence which conforms to the general rules for creating a definition and the specific rules constructed for creating a definition of this specific type of occurrence
  4. A short narrative description of the occurrence
  5. A long narrative description of the occurrence
  6. Entry data including:The name of the person entering the dataThe Organization ID of the person entering the data
  7. Approval data (one occurrence for each approval required) including:
      The name of the person approving the entry contentThe Organization ID of the person approving the entry content
  8. Maintenance data (one occurrence for each maintenance occurrence) including:The name of the person maintaining the entry contentThe Organization ID of the person maintaining the entry contentReason for maintaining the contents of this entry
Contact Martin Modell   Table of Contents

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.