Highlighting the project from the list and pressing the "Show" button will open the window used for managing the project. It allows you to define the parameters of the project, generate documentation and scan documentation (searching for comments to the project).

In order to define a new project, use the "Add" button which, when clicked, opens the project defining window. Use this window to set the basic parameters of the project such as: code, title, authors, company, keywords, category, subject and note. The code of the project must be unique within the Tormigo application. These parameters can later be used in the documentation template. Presented below is an example of a project configuration window.

On the right side of the project there is a panel which allows to define the repositories associated with the project. The "+" button allows to add a repository, the "…" button allows to edit the selected repository and the "-" button allows to delete it. The up and down arrow buttons allow to move the highlighted repository one position up or down in the list.

In order to add a new project, use the "+" button. Presented below is an example of a dialog window allowing to select a repository.

In the "The section name in the document" field, enter the name which will mark the chapter which starts documentation generation for this repository. Next, select the connection to the repository defined in the program from the dropdown list. Confirm the entire operation with the "Save" button.  If there is no defined connection to the repository, you can use the "New" button in order to define a new connection. If it is necessary to edit an already defined connection, select it from the dropdown list and then click the "Edit" button.

In order to add a new connection, click the "New" button. Define the parameters of the connection to the repository in the opened window. Tormigo, in order to display diagrams and linked documents (LinkedDocument) in the documentation, requires the provision of the path to the EAP file in the connection configuration. If you are using a repository based on DBMS, you can create an EAP file with a connection alias to the selected repository. In order to do this, open the project in Enterprise Architect and then select File | Save Project Shortcut from the main menu. Next, enter the path to this file using the "EAP shortcut" tab in the connection configuration window. The tab will be active only when defining a connection to a database other than an EAP file. Presented below is a window allowing to define the parameters of an EAP file alias.

Enter also the ‘Repository UserID’ and ‘Repository password’ if the repository requires authorization. These parameters will be stored in the Tormigo configuration. Tormigo stores all passwords in an encrypted form.

Presented below is an example of a project configuration window containing three assigned repositories.

Generation of documentation

Documentation generation for a project is opened by clicking the "Generate documentation" button in the project configuration window. Clicking this button will open the documentation generator window. The contents of the generated MS Word document will vary depending on the configuration of the template and the kind of generated documentation.  The user can define what types of elements will be included in the documentation.

Description of the documentation generator

The documentation generator window allows to define the parameters of documentation and to generate change documentation or documentation for selected packages. When generating change documentation, the application will post the following within the documentation:

• all packages which contain the change code in their name,   

• all packages which are assigned a Maintenance Change element which contains the change code in its name,

• all elements which are assigned a Maintenance Change element, which contains the change code in its name,

• all diagrams which contain the change code in the Notes field.
  

It is possible to determine the change code after launching documentation generation. By default, the change code matches the project code.

If documentation is generated for selected packages, the user can select packages which will be included in documentation for each repository.

Presented below is an example window of the documentation generator:

The documentation generator window is divided into tabs which allow to specify documentation template parameters, contents of documentation and buttons used to generate documentation.

Tab: Properties

The tab allows to specify the documentation template and its basic parameters.

The Template file field – allows to determine the path to the file with the documentation template.

The First chapter number field – allows to determine the value of the first generated documentation chapter. Setting the value to 0 disables assigning chapters with numbers.

The Maximum number of header to be  used in the chapter’s name field – allows to determine the highest number of the style which will be used in names of subsequent subchapters.

The Template panel – allows to open, save and delete documentation template settings.

Tab: Styles

The tab allows to define style names in a template. Default style names will be generated for the language used by Tormigo. Upon each defining of a template, check whether the template contains thus defined style names. During the document generation process, an attempt to use a style which is not defined in the template will terminate the document generation process providing an adequate notification. In addition, within the tab it is possible to define two parameters:

• Use header styles for element names – defines whether heading styles are to be used for element names (keeping the subchapters hierarchy). Leaving this field empty will cause the use of the Element style for the name of the element.

• Add numbers of pictures – determines whether the generator is supposed to number diagrams added to documentation.

Tab: Element types to include

The tab allows to highlight the element types which are to be included in the documentation. In order for an element type to be included, the checkbox next to the name of the type has to be checked. The “Select all” button causes the selection of all element types while the “Deselect all” button analogically deselects all element types.

Tab: Content

The tab allows to determine which element and package properties will be displayed in documentation. There are three panels in the tab:

• Element properties – defines which element properties will be displayed in the documentation,

• Package properties – defines which package properties will be displayed in the documentation,

• Options – defines which elements associated with packages and other elements will be displayed in the documentation.

Template file

Documentation is generated based on a template file. The template file is the pre-formatted MS Word document. The document must contain a clause {doc.Content} which will be replaced with the generated content. Within the template you can use the fields containing the following properties of the document: Title, Author, Company, Keywords, Category, Subject, Comments. During document generation these fields will be completed with the values defined for the project. In the MS Word program, use the option Insert / Text / Quick elements / Document properties / Author in order to insert a field with the authors of the project. Presented below is an example snippet of a template.

Generation of change documentation

Change documentation contains:

• all the packages which contain the change code in their name,   

• all the packages which are assigned a Maintenance Change element which contains the change code in its name,

• all the elements which are assigned a Maintenance Change element which contains the change code in its name,

• all the diagrams which contain the change code in the ‘Notes’ field.

Also included for each package and element which fulfils these criteria will be all the packages and elements they contain, which pass the filters defined in the template generator, such as e.g. Maintenance elements.

The change documentation generator searches the repositories assigned to the project one by one. In the first step it searches in the repository for packages which contain the change code (project code) in their name. For instance, if the generator (for the "PR-DK-01” change code) finds a package with the name "Description of the PR-DK-01 project”, it will include it with the generated document along with all the elements from its structure which were marked in the documentation generator window. In subsequent steps the system will search for the packages, and then model elements, which are assigned a change (Maintenance Change) with a name containing the change code. The last step of generating change documentation for a given repository is searching all the diagrams which contain the change code in the ‘Notes’ field too.

In order to assign a Maintenance Change in Enterprise Architect, mark on the project tree the element to which the change is to be assigned. Next, in the Maintenance window (ALT + 4) select the ‘Changes’ tab and click on the ‘New’ icon. Enter the (project) change code in the ‘Name’ field of the change description form. The change name can be supplemented with short information on what it is the change concerns. Complete the other fields of the form. After completing, click on the ‘Save’ icon to save the changes. Presented below is an example of a form describing the change of a requirement.

Change documentation generation is started by clicking the "Generate documentation of changes" button in the documentation generator window. The application will display a dialog window with a request to enter the code of the change in the project. By default, the change code value is the project code.

Clicking the OK button will start the documentation generation operation. Presented below is a part of the generated documentation containing a section from the documentation:

• package containing the change code in its name,

• requirement assigned to which was the ‘Maintenance Change’ change containing the change code in its name.  

  

Generation of documentation for selected packages

Generating documentation for selected packages is done by clicking the „Generate packages documentation” button in the documentation generator window. After launching the generator, the user can indicate the packages which will be

included in the documentation.

Selecting the „Insert the repository as a new section in the document” option will result in adding a separate subchapter for each repository.

Clicking the OK button will start documentation generation. Included in the generated document will be all selected packages along with the elements and diagrams posted in them. Presented below is a section of documentation for selected packages.

Documentation scan

The Tormigo Integration module also allows to scan project documentation when searching for notes to a model. The operation will find all the notes assigned to model elements in the indicated document. The condition for model element identification in a repository of a project is the inclusion of the element’s GUID number in the text to which the note refers. Presented below is an example of note assignment to a model element.

After starting the documentation scanning operation, the user must select the file with the documentation. Next, the application will try to find the model element in the repositories of the project for each note in the document. If the element is identified, the application will display a dialog window allowing to add a note as a Maintenance element to the model element.

The user can define the Maintenance element type and its basic properties. Selecting the „Apply the selected type to everybody and do not show this window” option will result in skipping this dialog window and saving all notes with default settings.

After clicking on „Save”, the element will be added to the model as a Maintenance element of the selected type, which will be assigned to the element to which the note referred. Presented below is a Maintenance window from Enterprise Architect with the Issue element added during the documentation scan.

Read more about Tormigo on the TORMIGO and TORMIGO movies websites.