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 the following tips and tricks might help developing a method 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

• Mark textblocks or sections, paragraphs and if necessary smaller parts or sentences, words
• Use abbreviations to mark these parts, for instance tb for textblock, tbl for table, par for paragraph, p for part
• Use brackets, e.g. < >, to mark the parts in the specification document and match these in the Blueriq implementation
• Refer to the parts to describe preconditions in the document

Example encoded text:

<tb1><par1_1><p1>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p1> <p2>Donec congue venenatis placerat.</p2> <p3>Etiam posuere, arcu ut vulputate ornare, eros lacus sagittis massa, et sodales tortor ipsum vitae arcu. Donec mattis interdum eros, vel egestas diam venenatis in. Vestibulum felis enim, hendrerit eget suscipit quis, tincidunt id augue. Nullam aliquam bibendum nisi. Cras eu venenatis lacus. Praesent vel pretium justo. Sed sed arcu lacus. Vestibulum fringilla magna purus, eu efficitur quam fringilla sed. Duis arcu magna, ultrices et sodales vitae, mollis vestibulum ante. Fusce suscipit nisl purus, quis faucibus nisl pellentesque vitae. Nam vitae lacinia magna, a pulvinar nulla. Fusce a lacinia felis, id congue dui. Aenean sollicitudin purus sit amet arcu vestibulum placerat. Morbi pharetra turpis ut sapien bibendum, sit amet dapibus purus volutpat.</p3></par1_1>

<par1_2><p1>Ut efficitur neque elit, et auctor sapien consectetur ac. Curabitur sem tortor, egestas ac elit vehicula, feugiat feugiat lacus. Vestibulum non justo venenatis, sagittis ipsum a, rhoncus odio. Aenean fermentum suscipit accumsan. Donec et pulvinar eros. Sed efficitur malesuada rhoncus. Morbi lobortis sapien augue, a efficitur metus facilisis et.</p1></par1_2></tb>

Layout

Implementing style guide

. 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

• RTF import or not?
• Prepare your RTF import (layout & content)