To learn more about best practices when automating a document, download the attached complete Module building: Best practices guide (please scroll to the bottom of this article) or read through selected best practices below.
Document Automation
OVO vs. BYOT (One-Value-Only versus Bring-Your-Own-Template)
|
One value only |
Whenever formatting such as font, size, or color or the omission of empty lines, rows, and columns is not necessary, authors can choose to simply reference all content into a Text Block Value Node called RESULT. This Node then needs to be mapped to the only placeholder in a template. This template could either be the built-in BRYTER template or a custom template with only one placeholder called {{RESULT}}. |
| This approach is usually best suitable for reports sent to the author or summaries that are not made available for clients. | |
|
Own template |
If the intended audience of a generated document is a client or anyone external, you should use your own Word template and use more than one Text Block Value Node to be mapped onto placeholders. |
| If you want to have more control over formatting text such as using different fonts, text sizes or colors and avoiding empty lines, you should use your own Word template with placeholders formatted accordingly or placeholders followed by commands such as {{\dl}}. | |
| If the Module’s main purpose is generating a document, start with preparing the template for automation. After all dynamic placeholders are defined, build the document automation Module. |
Placeholders
|
Quick templating |
If your document template already contains placeholders or indicators for dynamic content, for example in square brackets [], use the Replace functionality to Find [ and Replace with {{ - and respectively, Find ] and Replace with }}. |
|
Word Add-in |
Use the BRYTER Microsoft Word Add-in, to add placeholders and commands quickly. |
|
Naming |
The placeholders in document templates for variable values should have the same name as the variables in the Editor. If the Module finds an exact match, it will give you the option to automatically connect the placeholder sections in the Module with the document placeholders. |
|
For variables associated with document generation and document placeholders, underscoring {{company_name}} or Camelcase {{companyName}} should be used to avoid missing any placeholders due to accidentally placed whitespaces, e.g., {{company Name}} and {{company Name}}. |
|
|
If spaces are used in names and placeholders, enable the ¶ functionality to spot whitespaces quickly. |
|
| Commands |
Use command {{\dl}} to avoid empty lines in paragraphs in your Word template. |
|
Use command {{\dc}} to delete a column or {{\dr}} to delete a row in a table. Note: This only applies to tables inserted directly through the built-in table functionality in Word. Tables created inside the Rich Text Editor cannot be dynamically adapted. |
|
|
Avoid empty lines |
If some of the values in your Module that are mapped onto placeholders are skipped due to the conditions defined in your Modules, make sure to add the delete line {{\dl}} command after the placeholder in your document if the placeholder is the only text present in that line. |
Grammar groups
|
Dynamic inline references |
A Grammar Group can be used to ensure that the output document is grammatically sound and customized. This is especially useful when automating forms which specifically address a person whose gender is known. Instead of using hard coded variants (e.g., "the employee shall use his/her own computer"), use a dynamic inline reference using an @reference to an updated Text Block Node called “His/Her/Their”. Depending on the selected gender this Text Block Node is updated with the correct pronoun which leads to fewer Text Block Nodes. |
|
Naming |
Use an idiomatic Value name like His/Her/Their instead of something more descriptive such as personal_pronoun_third_person_singular. |