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 in case of complex documents containing variables, conditional texts or multiple languages:

• Encode/tag large texts, conditional parts and variables to match the specification document and the Blueriq implementation to ensure 'talking about the same thing' and support testing and implementing the document. Example:
  • 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
• Write variables in the Blueriq syntax, e.g. Person.Age to facilitate easy modelling in Blueriq and create shared knowledge about the domain
• Use the ability in Word or a text editor to place a comment on a part/code to describe the precondition of a part

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>

To 

Layout

Implementing style guide

• Styleguide
• Prepare stylesheets (print space & styleguide)

RTF import

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