ReqSuite® Requirements Manager (RM)
Document Definition

Once content modeling, model refinement, and template definition have been completed, the document definition serves as the final step in the configuration design process to design a result document that is usually required. This document should have a structure and appearance defined according to your corporate design and adequately present the content (i.e. concrete elements of a certain content type) that you develop within the framework of your projects based on the above-mentioned configuration. In this context, the document definition deals with

  • the desired chapter structure for subdividing the document
  • the layout and visual appearance of the document
  • the concrete representation of individual content elements by means of graphic, textual and/or tabular descriptions

The definition of a document template itself is done in MS Word® and uses the concept of so-called markers (also called tags). These are embedded in the template between three hash tags before and after the marker and are replaced by the actual description of the content elements and meta information as placeholders when the result document is generated in the plug-in.

Note: The description contents inserted automatically instead of the markers are always formatted (also within tables) using the “Standard” style sheet. Therefore, this style sheet should always be defined appropriately according to your corporate design.

Against this background, it is helpful to consider the structure of the content of the result document based on the previously created content model in advance and proceed as follows in order to define a corresponding template for this result document:

  1. Start MS Word® and open a new or empty document. If you already have a company-specific document template for the result document, you can alternatively open it.
  2. Create a chapter structure with headings for the result document based on the content types whose concrete content elements you want to explicitly list in the result document. For each of these categories, you create at least one logical section or distribute them to separate chapters in your document template and determine where the corresponding content elements are arranged.
    • Content types whose elements only serve as an intermediate product in the course of the project to develop other content can be ignored.
    • A content element can also be listed in several sections, e.g. in one section as part of a tabular or list-like overview and in another section as a detailed, textual or graphical description.
  3. Add the usual document components such as cover page, appendix, table of contents, table of tables, and table of figures, and format fonts, paragraphs, and headings according to your corporate design.
    Figure 1: Document template with ReqSuite® markers for the cover sheet (left) and information sheet (right) of an exemplary project specification sheet

     

  4. Define the concrete way in which the contents of a content type are displayed in the results document. The following complementary options are available, which are not mutually exclusive:
    • Part of a list: Content elements are output in the form of a dashed list with comma-separated attribute values.
    • Part of a table: Content elements are output in tabular form according to the format template that you can store in the open Word® document with the name “ReqSuiteDynamicTableTemplate”. This table template should be designed according to your corporate design in such a way that it vividly represents different contents of a content type, whereby the columns of the table represent attributes of a content element (e.g. name, description, etc.).
    • Independent detailed description: Content elements are displayed separately in the form of a paragraph or a table. In the case of a table, you can store a style template with the name “ReqSuiteTableTemplate” in the open Word® document. This table template should be designed in accordance with your corporate design so that you clearly represent the individual attributes of a content element, with each line of the table representing one attribute.
    • Independent detailed visualization: Content elements are represented by a graphical description using the notation stored for you (e.g. with the help of a diagram). Create a style sheet for texts with the name “ReqSuiteCaption” to format captions according to your corporate design.
    • Part of an overview graphic: Content elements are output as part of a graphic to visually describe the relationships of all content elements in a content category. To do this, create a style sheet for texts with the name “ReqSuiteCaption” to format captions according to your corporate design.
    • Headings: In addition, you can define any format templates that correspond to your corporate design with freely selectable names (without special characters) and use them in conjunction with certain document markers at all places where a format template can be explicitly assigned.
  5. Now set the corresponding markers in the individual sections of the template where they are to be replaced by the actual description of the content elements as shown, in the course of later document generation. The concrete use of more complex markers can be seen in the example template in Figure 2.
    Figure 2: Detail of a document template with more complex ReqSuite® markers in MS Word®.
  6. Save the opened Word® document and close it. To effectively store the template for the project configuration, i.e. to be able to generate a result document from the document template just defined within an open project, follow the instructions for uploading a document template in the configuration management (see also Figure 3).
Figure 3. Managing the Document Templates Stored for a Configuration

With the import of the document template via the WebApp into the ReqSuite® system, the configuration design process is now complete. Each project for which you define the just completed configuration in the project management will now have all the details of the configuration specification. This also applies to all existing projects that were already based on this project configuration before completion of the configuration process, provided that you update the project configuration.

Below is an overview of all document markers that can be used in ReqSuite® – divided into project general meta-markers and project-content-specific content markers – together with an explanatory description of the content to be inserted into the document.

ReqSuite Document MarkupContent Pasted Into Document
###PROJECT NAME###Name of the project.
###AUTHOR###First and last name of the person who triggered the document generation.
###TEAMMEMBERS###All persons with first and last names assigned to the project as users in any role.
###PROJECTLEADERS###All persons with first and last name assigned to the project in the “ProjectAdmin” role.
###VERSION###Baseline number of the project on which the document was generated.
###VERSION CHANGES###Changes of the current baseline to previous baselines.
###HISTORY###Table with history information about the different baselines of the project.
###CURRENT DATE (+<DAYS>)###Today’s date (or future date, which is anticipated in days after a certain period in days from today’s date).
###STATISTICS###Project statistics.
###OPEN ISSUES###List of all open clarification points.
###ALL COMMENTS ([<FILTER_ATTRIBUTE>{=|<>|<|>|<=|>=} <FILTER_VALUE>])###List of all comments across all elements (restricted according to the given filter attribute and filter value referring to the elements that include comments).
###ATTACHMENTS ([<FILTER_ATTRIBUTE>{=|<>|<|>|<=|>=} <FILTER_VALUE>])###List of all attachments across all elements (restricted according to the given filter attribute and filter value referring to the elements that include attachments).
###CONTENT PROBLEMS (WITH <ATTRIBUTE>)###Result of the quality checker results (including value of the attribute of the corresponding content elements).
###CONFIGURATION HANDBOOK (ON <FORMAT_TEMPLATE>)###Generates a manual of the project configuration on which the project is based (in a section according to the specified format template (e.g., Heading1)).
###<TYPE>:DOCUMENT###When generating documents based on a template including this marker, a ZIP file is exported containing one Word export for every element of the content type.
###DOCUMENT CHANGES###Changes of a particular document generated with the ###<TYPE>:DOCUMENT### marker to its previous version.
###DOCUMENT VERSION###Version of a particular document generated with the ###<TYPE>:DOCUMENT### marker.
###ENABLE INTERNAL LINKS###References from one element description according to the marker “<TYPE>:INSTANCES” to another element description are exported as clickable hyperlinks in the document.
###<TYPE>:OVERVIEWMODEL###Graphical overview notation of all content elements of the content type.
###<TYPE>:DEFINITION###Stored definition of the content type.
###<TYPE>:INSTANCEMODELS (ON <FORMAT_TEMPLATE> (INCLUDE ID))###Detailed visualizations of all content elements of the content type (with headings for each content element according to the format template (including “ID”)).
###TRACEABILITYMATRIX WITH <TYPE_1>, <TYPE_2>###Traceability matrix showing the relationships in pairs between all content elements of both content types.
###<TYPE>:<ATTRIBUTE>(:{SUM | AVG | MIN | MAX}) ([{<FILTER_ATTRIBUTE>{=|<>|<|>|<=|>=} <FILTER_VALUE> | ID=*}])###Attribute value of the first content element found (and/or sum / average / minimum / maximum attribute values (if number and/or date) of all content elements) of the content type (restricted according to the filter attribute and filter value, or to the ID of the content element to be exported with ###<TYPE>:DOCUMENT###).
###<TYPE>:INSTANCES (HIDETEMPLATE) (WITH INSTANCEMODELS) (WITH RELATED {HIERARCHY | CHILDREN}) ([{(DIRECT) <FILTER_ATTRIBUTE> {=|<>|<|>|<=|>=} <FILTER_VALUE> | ID=*}]) (ON <FORMAT_TEMPLATE> (INCLUDE ID)) (WITH (ALL) RELATED <RELATED_TYPE_1>{(:TABLE (WITH <ATTRIBUTE_1>, …)), (WITH INSTANCEMODELS)}([(DIRECT) <FILTER_ATTRIBUTE> {=|<>|<|>|<=|>=} <FILTER_VALUE>]), … (,ATTACHMENTS) (,COMMENTS)) (+)###Detailed descriptions of all content elements of the content type according to the defined structure (without output of the description template) (with detailed visualizations according to the defined notation) (with {all hierarchically, transitively linked elements | only with linked elements of the same type}) (with restriction of value selection for output calculation according to filter attribute and filter value) (with headline for each content element according to the format template (including “ID”)) (with associated content type(s) according to naming (each as table of respective content elements with all attributes / only with “ID” and “Description” / only with “ID”, “Name” and “Description” or named attribute(s) (with associated attachments and comments)) (with workflow status and element version).
###<TYPE >:LIST (WITH <ATTRIBUTE_1>, …) ([(DIRECT) <FILTER_ATTRIBUTE> {=|<>|<|>|<=|>=} <FILTER_VALUE>])###Dash list of all content elements of the specified content type with “ID” and “Name” attributes (or enumerated attribute(s)) (with value selection restriction for calculating the output according to filter attribute and filter value).
###<TYPE>:TABLE WITH <ATTRIBUTE_1>(|<DESIGNATION>), … (,RESPONSIBLE_USER) (,LAST_EDITOR) (,TEMPLATE) (,RELATED_COMMENTS) (,RELATED_ATTACHMENTS) (,INSTANCEMODELS) (,LAST_CHANGE) (,DEADLINE) (,CREATION_DATE) ([(DIRECT) <FILTER_ATTRIBUTE> {=|<>|<|>|<=|>=} <FILTER_VALUE>]) (({DIRECT|ALL}) <TYPE2> (([<TYPE2>.<FILTER_ATTRIBUTE> {=|<>|<|>|<=|>=} <FILTER_VALUE>]))###Table of all content elements of the specified content type with named attribute(s) (and alternative identifier(s) in the table header) (, with naming of the responsible user) (, with naming of the last editor) (, with detailed description) (, with related comments) (, with related attachments) (, with instance models) (, with date of last change (, with deadline date) (, with date of creation) (, with restricted value selection for output calculation according to filter attribute and filter value) (, with direct or all related elements of another content type) (restricted according to the filter attribute and filter value, or to the ID of the content element in the project or in the database).

Legend for table:
<…> Variable value
(…) Optional value
{…|…} Alternative values
[…] Regular brackets as part of filters

Note: You can also perform each of the modeling and definition steps described above subsequently and repeatedly to adapt your project configuration to changed project conditions, for example. In the case of several projects based on the same configuration, however, it is recommended that you create a new configuration instead of adapting the existing configuration.

For more hands-on details on the document definition features of ReqSuite, please take a look at the following tutorial video: