Clear, consistent, unambiguous terminology in products and documentation

Idea created by Michael_Lowry on Apr 13, 2018
    Not planned
    Score1
    • Michael_Lowry

    I recently discovered a limitation of  MODIFY_TASK: ‘active‘ in the context of MODIFY_TASK is not the same thing as ‘active’  in the context of the Task Properties window. These are distinct concepts, despite having similar nomenclature, display style (italics), and behavior.

    This reminded me of a product enhancement I submitted in November. It relates to the confusingly ambiguous and inconsistent terminology one sometimes sees in the Automation Engine and its documentation. I have already submitted this to Automic Product Management, but I thought it was worth reposing here to elicit feedback — and votes of support! — from the community.

     


     

    There are several cases where confusingly similar terms are used to describe different elements of the Automation Engine. I will provide three prominent examples where confusingly similar terms are used for distinct concepts:

    1. The term variable and related terms
    2. The term run number and related terms
    3. The term active and related terms
    4. The terms job plan, process flow, and workflow
    5. The term task in the context of workflows and executions
    6. The terms object and task in the names of AE scripting commands

     

    1. The term variable and related terms

    • A variable object is a separate type of object (short name VARA) that stores static tabular data or serves as a dynamic reference to an external data source.
    • An object variable is a variable defined in the Variables & Prompts tab of a UC4 object.
    • A script variable on the other hand is a variable defined in the Pre Process, Process, or Post Process tab of an executable object.
    • The term value is often used to refer to object or script variables set via the :READ command or a prompt set.

     

    The terms object variable and variable object are too easily confused with each other. Moreover, the use of these terms is not always consistent. Lastly, the technical distinction between an object variable and a script variable is not really clear. E.g., it’s possible to promote a script variable to an object variable using :PSET. Also, particularly in the context of prompt sets, the terms variable and value are often used interchangeably even though they appear to be functionally equivalent.

    VARA objects should probably be called variable tables, to better distinguish these objects from script variables and object variables.

     


     

    2. The term run number and related terms: ‘Run ID’, ‘Run number’, ‘Running number’, etc.

    • A task’s run ID is the eight-digit decimal integer identifier of an instance of an executable UC4 object, unique across the UC4 client.
    • The terms run number and running number are also used to refer to this unique eight-digit identifier many times in the documentation and user interface.
    • In the context of the MODIFY_TASK scripting command (and similar commands), the term running number is used to refer to the small (usually 1-3 digit) integer identifier that uniquely identifies each task in a workflow. The number corresponds to the order in which the task was added to the workflow. It is known as Lnr in the database.

     

    My instinct is to think of the long integers assigned dynamically to tasks by the Automation Engine as IDs, because they are unique, and they are not chosen by the user. Oh the other hand, the small integers that indicate the order in which a task was added to a workflow seem more like numbers to me, perhaps because of their ordinal nature. So perhaps it would make sense to refer to the former exclusively as run IDs and to call the latter simply task numbers.

     


     

    3. The term active and related terms: ‘Active’, ‘inactive’, etc.

    • In the context of the ACTIVATE_UC_OBJECT scripting command (and related commands), the term activate means execute, or submit for execution. When one uses this scripting command, it is equivalent to clicking the Execute button in the User Interface. This meaning of the term activate probably refers to activation, the first of the four stages of object execution (activation, generation, processing, and completion).
    • In the context of the Earliest tab of the Task Properties window, the terms active and inactive related to whether a task enabled for execution. If the Active attribute is set to NO, the task will still be a part of the workflow, but it will not be assigned a run ID, and will not be executed. Instead, it will be skipped and its state will be set to ENDED_INACTIVE.
    • In the context of the MODIFY_TASK scripting command (and related commands), the term active has a similar meaning to that in the previous example. However, the two meanings are not interchangeable because MODIFY_TASK does not change the state of the Active checkbox in a task’s properties. In fact, it cannot change the state of tasks whose Active check box is not checked. MODIFY_TASK alters only whether a particular task instance within a particular run of a workflow is enabled for execution.
    • In the context of the Attributes tab of a workflow or job object, and in the Activity window, the terms active and deactivate refer to whether detailed information about a completed task’s execution is retained and displayed in the Activity window.

     

    These four meanings of the same (or very similar) terms are different and not interchangeable. The  similarity of the names is therefore like to cause confusion, and likely to lead to design and programming errors.

    Consider the following example. Imagine that a colleague asks you “Is task ABC active?

    Do you know what she means by her question? Because of the ambiguous use of the term active within the product and its documentation, she could conceivably be asking one of four (or five) different questions:

    1. “Has task ABC been executed? (e.g, using UC_ACTIVATE_OBJECT)
      1a. Alternately, “Has task ABC passed the activation stage of object execution?
    2. “Is task ABC marked active in the Task Properties within its parent workflow?
    3. “Has task ABC been changed to active using the MODIFY_TASK command?
    4. “Does task ABC still appear in the Activity window, or has it been deactivated?

     

    This is just one example. There are many other similar situations related to variables or run IDs/running numbers.

     


     

    4. The terms job plan, process flow, and workflow
    The names of many APIs are inconsistent. Classes & methods related to the same concepts have quite different names. For example, JobPlan, ProcessFlow, and Workflow are three different names for the same thing, and there are classes based on each name. This is likely to cause confusion, particularly for those who are new to the product.

    • JobPlan
    • JobPlanAttributes
    • JobPlanCheckpoint
    • JobPlanDependencies
    • JobPlanEarliest
    • JobPlanExternal
    • JobPlanMonitor
    • JobPlanMonitor.Task
    • JobPlanTask
    • JobPlanTaskDependency
      ...
    • ProcessFlowGeneral
    • ProcessFlowGeneral.DeploymentDependency
    • ProcessFlowSettings
    • ProcessFlowSettings.AskForAlias
    • ProcessFlowSettings.ElseAction
    • ProcessFlowSettings.ExternalTaskStatus
      ...
    • WorkflowIF
    • WorkflowLoop

     

    I suggest aligning on a consistent set of terms for each concept, introducing classes & methods based on the new & consistent names, and then deprecating old APIs.

     


     

    5. The term task in the context of workflows and executions

    A task can refer to a task within a workflow (or schedule). It can also refer to an active execution in the Activities window (Process Monitoring perspective in the AWI). This is ambiguous.

     


     

    6. The terms object and task in the names of AE scripting commands

     

    Objects and tasks are different things, but the AE scripting commands that work with objects and tasks are often named in such a way as to obfuscate this important distinction. Tasks are active instances of objects. There can be only one object with a given name (in a client), but there can be many tasks associated with a given object. One can activate an object, but when one does so, one is actually starting a new task. One cannot truly activate, cancel, rerun, restart, roll back, or toggle the status of an

    object. These are actions one performs on

    tasks, and these actions have no effect on the underlying objects. With this in mind, the names of some of these scripting commands seem misleading.

     

    • ACTIVATE_UC_OBJECT
    • CANCEL_UC_OBJECT
    • DEACTIVATE_UC_OBJECT
    • RERUN_UC_OBJECT
    • RESTART_UC_OBJECT
    • ROLLBACK_UC_OBJECT
    • TOGGLE_OBJECT_STATUS

     

    Of all of the above commands, ACTIVATE_UC_OBJECT is the only one that works with objects. The rest of these commands work with tasks. Automic should consider introducing variants of misleadingly-named commands that are named in a more consistent way. Of course one cannot simply change the names of scripting commands. I appreciate the importance of maintaining compatibility. If it seems worth the trouble of adding more logically-named variants for these scripting commands, I’m sure this would be appreciated, particularly by new users of the product.

    It will be a challenge to present the new names in the documentation in a way that emphasizes the new names, includes the old ones, and does not cause confusion for new users. I’d say use only the new names in tables of contents, references to commands in the bulk of the documentation, and in examples; on the documentation page for the specific command, list the new (aptly named) names first, list the old names second, include a very brief explanation for why the new names were introduced, and provide a link to a more in-depth discussion of Automic’s effort to bring greater consistency to its product terminology. List all command variants in indexes.

    If you want to be really ambitious, you could also consider developing a mechanism for deprecation of commands, so that Automic can plan a gradual convergence on a consistent set of command names, and eventually retire the old command variants:

    • Deprecated commands could be highlighted in the script editor in a specific color or style;
    • A warning dialog box could be displayed to the user every time he/she saves an object that uses deprecated commands;
    • Warning messages could be printed to the Activation log each time an object is executed that uses deprecated commands;
    • A tool could be provided to help users find uses of deprecated commands; the tool could even update these uses from deprecated to supported commands automatically.

     

    On its own, just introducing more aptly-named variants of these (and other) commands would be helpful. However, it would be of most benefit as a part of a larger effort (alluded to above) to bring greater consistency to terminology across the product (and perhaps even product portfolio).

     


     

    Unambiguous terminology greatly simplifies conveying information about product features. This applies not only to the product documentation, but also to all other communication related to the product, including support incidents, emails between colleagues, product training, and so on.

    Automic should make a comprehensive review of its products, and come up with a clear, concise, and unambiguous set of terms, adopting new names where appropriate, to better distinguish between distinct elements and concepts.The product and the documentation should then be thoroughly reviewed to ensure consistent use of these terms throughout, and to eliminate instances of ambiguous or inconsistent terminology. When terminology choices have been made, every effort should be undertaken to ensure consistency.

     

    Legacy enhancement request ID: PMPER-130, opened November 2013.