Plan Your HotDocs Template Authoring Projects

This topic is intended as a general guide for planning large, complex template development projects. If you are developing a smaller number of relatively simple templates, following every step below may be unnecessary. You may still find the principles outlined below very useful.

A HotDocs template authoring project is the process by which you modify your existing documents to create HotDocs templates. For example, you may want to take a set of existing employment contracts and turn them into a single employment contract template that enables you to assemble several different types of employment contracts (e.g. full-time contracts, part-time contracts) from that single template.

Overview

If you have multiple large, complex text documents that you want to turn into HotDocs templates, you can benefit from using a structured process. The first steps in planning a template authoring project you accomplish outside the context of HotDocs Author. Generally, before reaching the step of creating a HotDocs template, it is good practice to prepare your documents by organizing them, marking changeable text, and finding commonalities between documents. Performing these steps first enables you to solve difficulties early in the project and ensure consistency in your final templates. You should review each step in the project planning process below.

Common Tasks

Among others, planning a template authoring project includes the following common tasks:

Workflow

There are typically eight primary steps you need to accomplish in planning and executing a template authoring project:

1. Organize Your Existing Documents

First, you should gather copies of the existing documents you want to convert into HotDocs templates and put them in a single folder on your hard drive. For larger projects, you should organize the documents into meaningful sub-folders. For example, by creating separate sub-folders for departments (e.g. HR, Marketing, Sales) or areas of knowledge (e.g. commercial loans, mortgages, deposits).

Steps

Organizing existing documents involves the following steps:

Collect the existing documents you want to turn into HotDocs templates.
Organize the documents into related categories.

With your documents organized, you are ready to mark up the changeable text in your documents.

2. Mark Up Changeable Text

Changeable text is any non-boiler plate text that you want to change with each document you create from a HotDocs template. Examples include names, addresses, optional paragraphs, and calculated numbers (e.g. sales results, taxes, etc.). In your HotDocs templates, you replace changeable text with placeholder fields. A placeholder fields acts as a references to a variable or other another component. These components define the kind of data (text, numbers, dates, etc.) HotDocs asks your template user for during the interview HotDocs generates from your template. The purpose of this step is to find changeable text before creating your template. This way, you identify where to place the placeholder fields in your template before you start creating each placeholder field and its corresponding component.

Steps

To mark up changeable text in your documents, use the following steps:

Open an existing document in Microsoft Word.
Identify all text in the document that should change with each document HotDocs assembles from your template.
Replace the changeable text with square brackets and a descriptive name; for example, the text John Smith becomes [Client Name], 11/28/2016 becomes [Transaction Date], and so on.
Repeat for all documents.

Using square brackets and descriptive text makes it easier to locate and understand the purpose of the placeholder in later steps. Once you mark up all changeable text in your existing documents, you can start identifying common data items across all your documents.

3. Identify Common Data Items

Common data items are any items of changeable text that appear in multiple documents, for example: a client name used in both a contract document and a cover letter document.

HotDocs enables you to re-use components between different templates. For example, you can create a Text variable called Employee Name in one template, and re-use the same Employee Name variable when an employee's name appears in a different template. This approach enables:

Consistency between templates
Less time spent creating duplicate components
Answers a template user provides in an interview for one template can pre-populate interviews for templates that contain the same components

Steps

Identifying common elements between documents involves the following steps:

Open an existing document in Word.
Copy marked-up items from that document into a list you create in a spreadsheet.
Repeat for all documents.
Where items appear in multiple documents, merge into a single item; this single item typically becomes a single HotDocs component.

Once you identify common data items, you can create a naming convention to help you clearly identify your components.

4. Create a Naming Convention

A naming convention defines rules for naming template components so that you can:

Identify a component's purpose in the template
Identify how the component relates to other components

We recommend that variable names have the format {Group}{Description}, where:

Group – refers to the overall area to which the information belongs
Description – briefly describes the information captured by the component

For example, imagine your template contains various variables to record information about an employee. You may have variables for the following information:

Employee name
Employee gender
Employee date of birth
Employee job title

For each item of information above, you can see that each of these items has a common group: Employee. You can therefore name each component using a common group prefix and adding a suitable description:

EmployeeFullName
EmployeeGender
EmployeeDateOfBirth
EmployeeAddress

This provides a clear and organized overview of your components, their relationships and their purpose.

Variable Dictionaries

To help with implementing your naming convention when creating templates, you can create a variable dictionary. A variable dictionary provides a predefined set of variable names that you can select when creating variables in your templates. This helps to to ensure consistent variable names across your templates. You will add the variable dictionary to your workspace, created in the next section.

Steps

Creating a naming convention involves the following steps:

Using the list of common elements, identify common groupings of components; for example, employee information or sales figures.
Create a list of prefixes using the common groupings. For example: Employee, Sales.
(Optional) Create a variable dictionary to help implement your naming convention.

Once you decide on a naming convention, you are ready to create your templates.

5. Create Your Workspaces and HotDocs Templates

A workspace is a folder on your computer's file system you designate (using Author) as a location for storing a set of (often related) HotDocs templates. The first thing you should do when you start HotDocs Author is to create a workspace using Workspace Explorer so that you can have a place to store similar or related templates.

A HotDocs template is a reusable HotDocs application containing boiler plate text and HotDocs script you build in HotDocs Author; HotDocs uses the template, along with user-supplied answer data, to assemble a customized document. In this step, you should create a new template for each of your marked-up documents.

When creating new templates from existing documents in HotDocs Author, make sure you use the Use existing content option in the New Template dialog.

Steps

Establishing workspaces and creating related templates in each involves the following steps:

Open HotDocs Author; then from the Workspace Explorer interface, create a workspace.
(Optional) Create a variable dictionary for your workspace.
Open an existing document in Word so HotDocs Author can use the content from your existing marked-up documents to create a HotDocs template.
Create as many templates as you want to store in a given workspace.
Repeat for as many workspaces as makes sense for you to create.

Once you create your templates, the next step is to create components and add them to your templates.

6. Create Your Components

Components are a basic building block of HotDocs templates. Components have properties you can set to establish the rules defining how HotDocs builds an interview, places answer data into your template, and assembles a document. To enable your template users to assemble documents, you must add components to your templates that define the data you ask your templates users for in the interview.

Steps

Creating components for your templates involves the following steps:

Open Component Studio.
Create a variable or other component for every item in your spreadsheet list above.
Open a template.
Add a placeholder for each marked-up item (i.e. your changeable text, identified by square brackets) in the template.

If you use Component Studio to create several components, you can dramatically benefit from using the Fast Field Insertion tool to add placeholder fields to your template.

Add other appropriate regions and rules, components or scripting to your template as needed. For example:
Repeat the steps above for all templates.

The individual steps are more fully described below.

6.1 Open a Template

In HotDocs Author, opening a template opens the template's DOCX file in Microsoft Word. Using Word, you can then replace your marked up content with HotDocs placeholder fields.

6.2 Add Placeholders and Create Components

In Word, you highlight a marked-up item, e.g. [Client Name]. Knowing that this item represents a changeable item of text, you add a placeholder for a variable. This replaces your selected text with a Text variable you can call Client Name.

You should replace all other marked-up text in the document, adding variables, instructions, and computations as required.

Test Assembly

While you are adding components to the document, you can test your template at any time to see how your interview flows, how well it works, and how HotDocs assembles a personalized document from your template. This enables you to see how the things you are doing are working while you are still editing the template.

6.3 Add Appropriate Scripting

If you want to change how the interview presents a dialog's contents as questions in the interview, you can create a script to control how the variables on the dialog behave. With a dialog script, you can also add appropriate instructions, expressions and computations to your dialogs. For example, you can use scripting to conditionally SHOW and HIDE answer fields, calculate values, or format text.

6.4 Repeat for All Templates

Once you complete your first template, repeat the process for your remaining templates. If there are any common data items, share the components from the first template with any others that need to gather the same information, rather than creating new components.

Once you finish authoring your templates, you should double-check your work by by testing your templates again.

7. Test Your Templates

Test in HotDocs Author is the button on either a component, or the HotDocs Author ribbon that opens the HotDocs Test Browser so you can check that either a component or a template works as you expect. When testing a component or testing your templates, you generally want to check that:

The correct questions appear in the interview
The final assembled document contains the correct content

To test both criteria, we recommend testing templates using the following steps:

Write test scenarios
Test Assemble the completed template
Perform user testing
Iterate – make changes to your template based on user testing

These steps are described below.

7.1 Write Test Scenarios

As the template author, you should have a clear idea of how a template works in different situations. For example, you should know that a particular paragraph of text is only included in the final document when your template user answers a particular series of questions. For particularly complex templates, it is often useful to write down specific test scenarios. For example:

Show the EmployeeContractLengthNm question in the interview only when the user answers Yes to EmployeeTemporaryContractTf
Ask the ClientChildrenDlg repeat dialog in the interview only when the users answers 2 (or greater) to ClientChildrenNumberNm

Taking the time to do this makes it easier for you to systematically test your templates.

7.2 Test Assemble the Template

With your template open in Word, clicking the Test button on the HotDocs Author tab of the Word ribbon causes HotDocs to generate an interview based on your template, and to present this interview in the Test window. This interview enables you to test a template before you upload your template to HotDocs Advance.

Answer Files

HotDocs enables you to save answer files during the interview. This is particularly useful when testing: it enables you to type answers for a specific test scenario into the interview, save those answers, and then re-using the answer file when you need to re-test the template.

7.3 User Testing

User testing refers to making your templates available to specific template users. The intention is that users:

Discover any errors in the interview process.
Discover any errors in the assembled document
Check interview layout, prompt text, help resource text, etc., for errors.
Provide you implementable feedback on the items above.

This process enables you to receive feedback on how actual end users actually use the templates before you make a general release.

Making a Limited Release for User Testing

You must first log in to HotDocs Advance in order to make a limited release:

In HotDocs Advance, create a new Work Group for test templates, e.g. titled Templates Beta Test.
Create a new User Group for test users, e.g. titled Beta Testers.
Assign the specific users you need for testing to the Beta Testers user group.
Assign the user group access permissions to the Templates BetaTest.
Upload your templates from HotDocs Author to Advance (see below), assigning the templates to the Templates Beta Test template group.

The templates are accessible through the users' Advance user accounts. They can perform interviews and assemble documents.

7.4 Iterate

If testing identifies any errors, you may need to go back and change parts of your template. Initial testing with a limited number of users is useful as it identifies any problems with the templates before you make your templates generally available. Once you have made changes, you should re-test the templates to make sure everything works correctly.

8. Upload Your Templates

When you complete testing in HotDocs Author and are satisfied that your templates work correctly, you can upload them for your template users. If you are using HotDocs Advance, you must:

Add an upload destination to your workspace.
Upload your templates to HotDocs Advance.
Assign the templates to a work group.
Assign access permissions to a user group for the work group.

Users can then use the templates to perform interviews and assemble documents. For more information about administering templates in HotDocs Advance, see the Templates section of the HotDocs Advance help file.

Common Reference Topics

Among others, the following reference topics relate to this conceptual area: