Getting started

A document model can be seen as a tree. The view in Blueriq on the left side is called the Tree View, see an example on the right. Whether a document was created using the RTF import wizard or a document is modeled from scratch it is advised to think about the intended structure and styles before starting or modifying (in case a document was imported).

Define the smallest unit

Before you start modelling define the smallest unit. A unit most likely will be either a word, sentence or paragraph. Hence, it is possible to form a sentence over multiple nodes adding conditions on parts of the sentence, example:

This structure could be the corresponding tree with a sentence "The <2a>applicant</2a><2b>applicants</2b> are required to provide all necessary papers", with a precondition on node 2a and 2b dependent of the number of applicants.

This could also be achieved by creating a node with one sentence and apply conditions within the sentence by selecting a part and click the 'add condition' button. However, in complex documents with many conditions on phrases and when using the specification method to encode a specification document breaking up the document in small units could be very helpful as the nodes could be named after the code or tag in the specification document.

Tree model

A document model can be seen as a tree with different types of nodes. Some of these nodes depict which child elements are allowed. For instance, the content style Table can be applied on a node. Consequently child elements may only have few types of content styles (for example TableRow). These settings can be changed in the Global Element of the content style.

Default a document tree model contains the following content styles determining the structure:

Paper type (Normal/Letter/Column)

Header(s) (-First/-Last)

<content>

Body

<content>

Footer(s) (-First/-Last)

<content>

Within one document the structure above can occur one or more times, for example in case of appendices or a cover letter. 

In the example above the root node has a content style of either Normal, Letter or Column. These three styles are out of the box styles and can be used directly. Please have look at the print space examples in the previous part for examples of a Normal and Letter style. The style Column will divide the document into 2 columns by default, these and other settings can be changed in the style sheets (xsl files) for the style Column as for Normal and Letter. Also it is possible to create a (custom) style or variation by introducing a label to correspond with the corporate branding. 

The global elements of these content style depict what styles are allowed as child elements.  

A full grown tree has many branches each branching off even more until small branches end with leafs. To create a maintainable and readable document model nesting and branching is strongly recommended. Most content styles require nesting (e.g. Table, TableRow or Letter), but it is recommended to apply nesting also if only for structuring purposes. 

Reusable elements

Content items can be used as reusable components in Documents. Other reusable components are Images and Text items. 

Possible uses can be:

• A content item could be a way to import new text or tables with the RTF import wizard. For example, an existing document requires change. The change includes adding many tables a lots of text. It will not be possible to use the RTF import wizard to update an existing document, but it is possible to import the new tables and texts and save them as content items. These content items can be added as node in your document as reusable item or it is possible to temporarily add the item and extract the contents by copy-pasting it elsewhere in the document.
• Large documents can get harder to maintain. Saving elements of the document as content item can make version control and searching easier. That is, changes made in a document (without content items) are not registered at a node level. In a large document it thus might be hard finding the change. Breaking up the document in content items will get around this, because changes will be registered at content item level narrowing the down parts of the document affected by a change. The same benefit holds for searching for content in a document. When the document's content is cut up in content items, the content item will occur in the search results instead of or next to the whole document. 
• Content like an addressblock, footer, header, signature (Image), contact info or even whole paragraphs or letters often occur in multiple letters and documents. Create content items to reuse elements that occur often.

To maximize reuse in a maintainable way split content and layout as much as possible. This requires a style guide to avoid needing to specify layout like fontfamily or colors in the document model. Another way at a smaller level to split content and layout is to apply conditions and styles at the node instead of within the textbox. In this way the contents of the node can be reused even if the layout or condition deviates.

Logic and nodes

Repeat conditions

Using repeat conditions is an effective way of keeping the document model small and structured. If possible, group nodes that require the same context, e.g. Application.Applicants. This will only require one repeat condition and will keep the model structured. The same applies to the use of preconditions. 

Reusable expressions

Often a document serves as a final report or copy of a process. For archiving purposes or as a copy for a client or user. Data in the document thus must be consistent with data send to any back office or database or data shown to users during the process. This should encourage the use of reusable expressions or auxiliary attributes instead of defining new expressions in the document model. Additional benefit: maintainability increases as new rules will only need to be changed once to be applied in pages and documents for instance, creating a more robust application.

Node conventions

The document tree displays an overview of nodes, collapsed or expanded. These nodes can be assigned a name. A name is not required and does not have a functional purpose. However, assigning descriptive names will contribute to a readable document model and set up naming (and modelling) conventions is recommended. 

Recommendations nodes:

 Apply nesting in the document model to create structure. If necessary, add empty nodes just for the purpose of grouping nodes together. 

 Set up node naming conventions, examples: (1) codes/tags from the specification document or (2) the first three words of a sentence (3) or name the node after its content style (e.g. AddressBlock) since the content style cannot be traced back by looking at the tree view or (4) a combination of these.

Handle exceptions

While testing a newly modeled document it might have occurred one or two times: a red obvious error message in the document. These exceptions have to me modeled explicitly when adding new styles or functionality (custom). Out of the box many exceptions are already present, for example an error when using the style TableRow outside a Table. 

Handling exceptions appropriately is important. When exceptions occur but no error message is shown in the output document, it might appear as no exceptions exist, especially in large documents. Hence, when adding new functionality or styles make sure error messages are implemented as well.