Specifications

When documents are a crucial element of the total Blueriq solution well defined specifications are important. Specifications about both content and layout.

Content

Especially when a document contains many variables and conditional texts it is recommended to agree upon a method to share specifications for the initial development and to support future changes. How to agree upon this method depends on your application, type and number of documents and organization.

One method is to encode/tag the specification document in your text editor. Sharing/creating this document with both the Product Owner and the Blueriq Engineer creates a shared understanding of the specifications and will help modelling the document in Blueriq Encore. This could be particularly helpful in case of complex documents containing variables, conditional texts or multiple languages. Possible units to encode could be variables (mark between opening and closing tags <var> </var>) or paragraph <par>, textblock <tb> or a part of a sentence <p>. These units can be numbered to specify which textblock or paragraph is meant, e.g. <tb2><par_3>Lorem impsum... facilisis et.</par_3><par_4>... etc.

These units can be used to describe preconditions that apply on certain parts, e.g. {tb2_par_3_p1} would describe a part of sentence in paragraph 3 of textblock 2. An precondition could be: Person.Age > 18. These preconditions could be described in a requirements table or as a comment placed in the text (possible in Word).

Note: any other method could work for your application. When the document does not contain many conditional texts within sentences the above method might be overdone. Moreover, when your modelling many documents with overlapping content, e.g. letters with only small differences, the above method could work well, but finding the patterns of the overlapping content and plotting this in a spreadsheet could be more valuable.

More important than a specific method to share specifications: think about and determine a method, keep it simple and worth the effort. 

Layout

Several content and presentation styles are provided out of the box. These include styles to make text bold or italic, to create a table with table headings, to create a document in letter or column style (available as content styles and differ from the content style normal with regard to margins and the allowed styles on children nodes) and so on. But also a default font family and font sizes are available and described in the delivered style sheets. 

The styles out-of-the-box are easily used and applied. But what if your organization has its own branding, a specific font family and size, branding colors and so on? It is possible to define these as presentation styles, using fontsize_[x] to increase/decrease fontsize or change the font family using fontfamily_[fontfamily], but this method should be an exception. Rather, a corporate branding or identity is provided and translated to a style sheet (xsl files). 

Style guide

A corporate branding guide contains all information about the layout used in your organization, hence margins, colors, fonts, headings, tables, images etc. This corporate branding can be translated to a (technical) style sheet and will take some custom coding, but clearly a corporate branding is custom for your project. 

To be able to create these corporate branding style sheets, henceforth style guide, a print space can be used. An example of a print space for the style Letter and Normal can be found below (in Dutch). A print space shows which and where elements should be placed on the document.The example below shows a print space for the first page and subsequent pages. In the style sheets the exact position of each element can be defined, e.g. left margin: 10 mm.

Benefits of defining a style guide and using a print space:

 A print space provides a shared understanding of how a document will look like and where elements will appear

 A print space provides an overview of all elements: no misunderstandings

 A style guide will reduce the number of custom presentation styles

 A style guide will separate layout from content

 A style guide will enable changes in the layout without the need to modify the document models

 A style guide can provide a showcase of possibilities and agreements (tip: model a template containing all styles as demo and model example)

Ideally the corporate branding should be available before modelling a document as this will enable a "first-time-right" development. A style guide (style sheets corresponding to the corporate branding and printspace) only has to be implemented once after which it can be used for all documents to come. 

RTF import

Before you start modelling a document consider importing an RTF document using the RTF import. Using the RTF import may much time especially when the document contains many (long) texts that otherwise will have to be copied and pasted into the document model. 

The RTF import wizard lends itself particularly well when:

• Document contains a lot of (long) textblocks with or without variables and/or
• Requirements are fixed and clearly delivered in a specification document and/or
• Document contains tables and/or
• Single paragraphs or tables are imported as content item (check the option to save the import as content item instead of document) to be used as reusable items in a document.
  
  

Recommendations:

  During RTF import: create a hierarchy or nesting in the document model by checking "Style acts as a parent node" for readability and maintainability.

  During RTF import: create a root node to be able to move nodes easily. Furthermore, styles applied on the rootnode automatically created at the top of the document model are ignored while rendering a document. Creating the (extra) root node during RTF import will help setting up the correct document model.

  "Clean" the RTF document before import. That is, make sure all styles used in the document are applied consequently. All paragraphs, headings... that look the same actually have the same style by using the format painter for example. During the RTF import these styles have to be matched to content and presentation styles in the document model.