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 a lot of 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 these method depends on your application, type of document and organization, but one method is to encode/tag your document. This could be particularly helpful in case of complex documents containing variables, conditional texts or multiple languages. For instance think about encoding/tag large texts, conditional parts and variables to be able to match the specification document and the Blueriq implementation. 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 lots of conditional texts within sentences the above method might be overdone. Keep it simple and worth the effort. 

Layout

Default 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 contains any information about the style used in your organization, hence margins, colours, 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. 

To be able to create these corporate branding style sheets, henceforth style guide, which form 'the recipe' for the document 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 elements are present on the first page and the subsequent pages and the margins. The exact position of the elements can be described apart from the print space by referring to the elements, e.g. page margin left (linker marge in Dutch): 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 that require some thought and tuning, hence: no misunderstandings

 A style guide will reduce 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 will provides 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 a RTF document using the RTF import. Using the RTF import might save a lot of time especially when the document contains a lot of (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
• Single paragraphs or tables 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.