Five Principles of Efficient Document Automation

From HotDocs Wiki

Jump to: navigation, search

Template developers interested in creating consistent, safe, and efficient templates should adhere to a few basic principles of document automation. Although there may be circumstances where some of the principles must be adapted, modified, or on rare occasions even ignored, in general, these principles are vital to ensure that your templates will produce quality documents.

The five principles are:


Principle #1: Fully Qualify All Variable References

This is perhaps the most important principle of document automation. Fully qualifying variable references means that variables should never be referenced in a template under conditions that are less restrictive than those under which they are asked. In other words, if a variable is relevant only under certain conditions, it should be asked or referenced only if those conditions are met. The following computation script violates the principle of fully qualifying variable references:

Principle 1.1.png

This script first tells HotDocs to ask Dialog A, which contains the variable TrueFalse Var A. If that variable is true, HotDocs asks another dialog, Dialog B. This dialog contains TrueFalse Var B, which, if answered true, causes a third dialog, Dialog C, to be asked. Since Num Var C is contained in Dialog C, it is asked only if the two True/False variables are true.

The problem with this script is that the ZERO( Num Var C ) > 50 test then assumes Num Var C will not have an answer unless both TrueFalse Var A and TrueFalse Var B are true. However, this is not a valid assumption. For example, suppose a user assembles a document with a new answer file and answers TrueFalse Var A and TrueFalse Var B as true, then enters a value of 100 for Num Var C. Then suppose the user decides to assemble a document for another situation without opening a new answer file. Starting over, the user answers TrueFalse Var A as false, so neither TrueFalse Var B nor Num Var C are asked. But Num Var C still retains its answer from before and the test ZERO( Num Var C ) > 50 comes out true. Thus "something" gets done when it should not.

If the ZERO( Num Var C) > 50 test is changed to simply Num Var C > 50, the script becomes only slightly less dangerous. In this case, Num Var C is asked (because it is used but hasn't been asked yet) when it shouldn't be. If the user realizes an irrelevant question is being asked and ignores it, well enough. But if the user answers with something greater than 50, "something" again gets done when it shouldn't.

To adhere to the fully qualified principle, the last portion of the above script should read:

Principle 1.2.png

Principle #2: Ask Only Relevant Questions

When automating templates, you should script interviews and dialogs in a way that prevents HotDocs from asking irrelevant questions. Thus, the user should only see and answer questions whose answers will actually be used at a later point in the interview or in the document.

There may be some situations where the cost of avoiding irrelevant questions is so high in terms of scripting effort or end-user confusion that a decision is made to present dialogs that include potentially irrelevant questions. For example, suppose the cover page of a document lists the name, city, and state of an individual. Later on, the individual's name and full street address are listed, depending on certain conditions. It is probably more sensible to ask for the entire address in the first place rather than to ask for city and state early on and for street and zip code later in the interview, after it is known whether they will actually be needed.

When making such decisions, developers should keep in mind that users can lose confidence in products when they are required to answer questions they later discover are not relevant. But users can also become irritated if the sequence or manner of asking questions is unnatural or overly complex.

Principle #3: Let Users Answer Only Questions That Should Be Answered

Interviews and dialogs should be scripted such that users can answer everything presented. Users should never encounter a situation where the thought is, "Since I answered 'yes' to question 7b above, I know I have to leave this question blank." Instead, dialog scripting should be used to gray or hide the question.

Of course, there will be situations in which it is not possible to know whether the user can answer a given question. One example is an agreement where, if the effective date is known at the time of assembly, it is answered and inserted into the document. If the effective date is not known, it is left unanswered and blanks are inserted into the document so the effective date can be penciled in at the time of signing. In such cases, it is acceptable to present a question (e.g. effective date) that may be left unanswered, but only if you clear Warn when unanswered at the Advanced tab of the variable editor.

Principle #4: Do Not Ignore Unanswered Question Warnings

Documents, dialogs, and interviews should be scripted such that the software can accurately report whether everything needed to produce a complete, valid document is answered. Unanswered warnings, when issued by the software, should always be meaningful. Users should never encounter a situation where they say, "I know HotDocs is telling me something was left unanswered, but I know I can ignore it and still get a good document." Nor should they say, "This question doesn't apply to me, so I'll put in 'XXXX' to keep from getting an unanswered warning." Spurious unanswered warnings can be avoided by following the principles above and by clearing Warn when unanswered at the Advanced tab of the variable editor for variables that are optional.

This principle is especially important in HotDocs 6 and later versions because answer gathering and document assembly occur separately. At the Document tab, HotDocs issues an unanswered warning if any variable actually used in the document is unanswered. At the Interview tab, HotDocs issues an unanswered warning if any variable included in any dialog in the interview is unanswered, regardless of whether the unanswered variable is actually used in the document or not.

Principle #5: Random Answer Should Produce Consistent Documents

You should script templates, dialogs, and interviews such that a user who provides random answers to questions will still receive a valid document for the answers given, as long as all questions are answered. There should be no inconsistency in the document or set of documents produced, regardless of the answers a user gives.