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.
Print space Letter
Print space Normal
RTF import
- RTF import or not?
- Prepare your RTF import (layout & content)
Previous: 1. Documents solution