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 principals 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.
In this Topic Hide
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.
Among others, planning a template authoring project includes the following common tasks:
There are typically eight primary steps you need to accomplish in planning and executing a template authoring project:
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).
Organizing existing documents involves the following steps:
With your documents organized, you are ready to mark up the changeable text in your documents.
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.
To mark up changeable text in your documents, use the following steps:
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.
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:
Identifying common elements between documents involves the following steps:
Once you identify common data items, you can create a naming convention to help you clearly identify your components.
A naming convention defines rules for naming template components so that you can:
We recommend that variable names have the format {Group}{Description}, where:
For example, imagine your template contains various variables to record information about an employee. You may have variables for the following information:
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:
This provides a clear and organized overview of your components, their relationships and their purpose.
Creating a naming convention involves the following steps:
Once you decide on a naming convention, you are ready to create your 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 logic 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.
Establishing workspaces and creating related templates in each involves the following steps:
Once you create your templates, the next step is to create components and add them to your templates.
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.
Creating components for your templates involves the following steps:
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.
The individual steps are more fully described below.
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.
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.
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.
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.
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.
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:
To test both criteria, we recommend testing templates using the following steps:
These steps are described below.
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:
Taking the time to do this makes it easier for you to systematically test your templates.
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 Hub.
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.
User testing refers to making your templates available to specific template users. The intention is that users:
This process enables you to receive feedback on how actual end users actually use the templates before you make a general release.
You must first log in to HotDocs Hub in order to make a limited release:
The templates are accessible through the users' Hub user accounts. They can perform interviews and assemble documents.
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.
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 Hub, you must:
Users can then use the templates to perform interviews and assemble documents. For more information about administering templates in HotDocs Hub, see the Templates section of the HotDocs Hub help file.
Among others, the following reference topics relate to this conceptual area: