Index by title

Adding new document templates

Installing a document template

With Modelio Document Publisher, document templates do not have to be delivered with modules. They can be exchanged directly by email and manually deployed. This can be particularly useful when updating document templates.

2

Installing a document template

Assembling documents

The Book template

Advanced use of Modelio Document Publisher begins with the use of the Book template. This is used to assemble different documents, in order to produce even more complete documentation without modifying document templates in any way.

Document assembly

2

Document edition using the Book template

We can see here that the document being edited will be generated by applying its template on two different documents. The structure diagram clearly shows this construction in detail:

3

Document combining Requirements and the Dictionary

Generating complex documents

With this construction, there are several different generation possibilities:

Note: The Book template can also assemble artifacts containing file links: an easy way to insert an image or a text at the beginning of your generated document.


Inserting external documents

Principle

Sometimes combining documents using the book template is not enough. You may want to add a message or an image in a specific part of your generated documentation.

Modelio Document Publisher has a solution for this use case:

Inserting a document

Document Publisher relies on the document’s target format to handle the inserted file type. For example, you can insert a “.txt” file  in both HTML and OpenXML formats, but “.docx” files can be inserted only in OpenXML generation mode. According to your system configuration, you may have to actualize your document content (using F9 for Word and usually F5 for your web browser) before seeing the inserted files.

The image below shows how to insert an image in the documentation generated for a Use-Case.

2

Inserting an image

When generating the document, the image is inserted at the same location as the current “description” note:

3

The inserted image in the generated document

Inserting a link

An << External Document >> note can also be generated as a link, rather than a direct insertion.

Just check the “Is a link” property in the “Annotations” view, and add a label if you do not want the hyperlink to be explicit, as shown below:

4

Switching to link insertion

When generating the document, the hyperlink is inserted instead of the image, and the label is displayed:

5

The inserted link in the generated document

Document Publisher parameters

2

Document Publisher parameters
List of options:

Customizing stylesheets

Open XML

Modelio Document Publisher is delivered with several stylesheets for the Open XML format:

Variants exist to support fr/en versions, as well as colors.

These are situated in the “$MODULE_DIR/res/stylesheet/” directory of your module catalog.

These stylesheets can only be modified using Word (2007 at least), by editing the definition of the styles they contain. The new stylesheet can then be applied to a document, and generation carried out.

HTML

Several stylesheets are provided for the HTML format:

They are situated in the “$MODULE_DIR/res/stylesheet/” directory of your Modelio installation.

This stylesheet can be directly modified using a text editor, simply by editing the definition of the styles it contains. The new stylesheet can then be applied to a document, and generation carried out.

ODT

Modelio Document Publisher is delivered with a stylesheet for the ODT format:

It is situated in the “$MODULE_DIR/res/stylesheet/” directory of your module catalog.

This stylesheet can only be modified using Libre or Open Office, by editing the definition of the styles they contain. The new stylesheet can then be applied to a document, and generation carried out.


Creating or updating templates

The template editor

With the Modelio Template Editor, you can define your own document templates using a dedicated graphical editor with absolutely no programming necessary, to generate documentation that really meets your needs.

2

The Use-Cases template in the Template Editor

All standard document templates are available as examples, and therefore can be used as basis to design your own custom document templates.

Note: A complete tutorial is available on the modeliosoft website.


The Introduction topic

The Introduction topic of the Modelio Document Publisher user guide tells you everything you need to know to get off to the best possible start with this professional documentation generation tool.

The Introduction topic contains the following sections:


The General Principles topic

The General Principles topic of the Modelio Document Publisher user guide describes in detail how to create, generate and visualize documents.

The General Principles topic contains the following sections:


The Generating Documentation topic

The Generating Documentation topic of the Modelio Document Publisher user guide provides information on the range of available document templates for use with Modelio Document Publisher. It also explains how to customize documentation generation, how to edit document contents and how to include model elements in a given document.

The Generating Documentation topic contains the following sections:


The Advanced Options topic

The Advanced Options topic of the Modelio Document Publisher user guide provides advanced information on document assembly, stylesheet customization, document template addition and Document Publisher customization.

The Advanced Options topic contains the following sections:


Document template catalog

Introduction

Modelio Document Publisher is delivered as standard with a number of document templates. These document templates are available exclusively in English at this time.

Directly usable document templates

Template When Applies to Purpose Description
Analysis & Design Analysis and design stages. Packages Overview of the project’s model. Deep exploration into the static and dynamic structures of the model, based on packages.
BPMN Analysis stage PackagesOverview of the BPMN's processes.Catalog of all BPMN processes presenting their detailed content.
Book Always Documents
Artifacts
Assembly of documents or external files. Enables the assembly of different documents in order to build a more complex document.
Ex.: combine "Requirements" with "Dictionary".
Class Reference Development, maintenance, implementation and design stages. Packages Reference list of all classes, interfaces, enumerations and data types. Provides a list of all classes, interfaces, enumerations, data types and their description. Alphabetically sorted.
Deployment Reference Project management, integration and deployment. Packages Reference list of all productions and external elements. A catalog of all Artifacts. Detailed description of each Artifact, including its kind (i.e. stereotypes) and manifested elements.
Diagrams Notebook Always Packages Reference list of all diagrams. Catalog of all diagrams by type, sorted alphabetically.
Process Analysis stage Packages Catalog of all processes presenting their detailed content.
Use Cases Analysis, requirement analysis. Packages Documenting the use cases of a system. Overview of all actors and use cases. For each use case, a detailed description of its content is added (notes and scenarios).
N.B.: Interactions contained in use cases are described as scenarios. Interesting combination with the "Requirements" template provided by Analyst module.
Dictionary (Extended) At the beginning of a project Dictionaries Glossary of a model's domain Can be used as an independent glossary or embedded in another document. More detailed than the Simple Dictionary.
Dictionary (Simple) At the beginning of a project Dictionaries Glossary of a model's domain. Can be used as an independent glossary or embedded in another document.
Goals At the beginning of a project Goal containers Goal analysis Documents goals.
Impact Development, maintenance, design Packages Impact analysis report
Business Rules At the beginning of a project Business rule containers Business rule analysis Documents business rules
Requirements At the beginning of a project Requirement containers Requirement analysis Documents requirements with their natures and properties. Don't forget to produce a document when packaging a requirement RAMC. Interesting combination with the "Use Cases" and "Traceability Matrix" templates.
Business Rules Properties At the beginning of a project Business rule containers Definition of properties attached to business rules.
Goal Properties At the beginning of a project Goal containers Definition of properties attached to goals.
Requirement Properties At the beginning of a project Requirement containers Definition of properties attached to requirements.
Traceability Matrix Design, development, maintenance and implementation stages Packages, goal containers, business rules, requirement containers Analysis of the traceability links between model and Requirement Analyst elements.

Editing the contents of a document

Document contents

The content of a document can be modified in the second tab of the document edition window, as well as in the second page of the document creation wizard.

2

Editing the contents of a document

Key:

Note: The addition of tables is currently possible only for generation in Open XML format.


Configuring documentation generation

Before you begin

Document edition is fairly similar to document creation, and is used to configure the main generation options.

To open the edition window, select a document and click on the  "Edit properties" icon in the module’s properties page.

Generation properties

Generation properties are defined in the first tab of the document edition window, and in the first page of the document creation wizard.

3

Document edition, generation properties
List of fields:

Including model elements

Generation roots

Model element inclusion is simply the edition of generation roots. This takes place in the third tab of the document edition window, as well as in the third page of the document creation wizard.

Adding model elements

2

Including model elements

Key:

  1. This toolbar is used to add new model elements or to remove already included elements, as well as to reorganize elements already included.
  2. This zone presents the set of model elements that will be used as generation root.
  3. This is used to automatically generate a diagram of the document structure, situated within the document in the model.

Note 1: Rather than using the toolbar to add a new model element to generate, you can drag & drop one from Modelio’s explorers.

Note 2: The generated document structure diagram simply enables you to see which model elements are going to be used as document generation roots.


Glossary


Introducing the Modelio documentation generation

Introduction

Welcome to the Modelio Document Publisher user guide!

The Modelio Document Publisher module enables you to automatically generate several different types of document based on models built in Modelio.

Modelio Document Publisher can generate documentation in two different formats:

Predefined document templates

Modelio Document Publisher is delivered with several predefined document templates for use throughout your project’s lifecycle.
Check out our document template catalog for an overview of the numerous document templates available.

Customizing documentation generation

Predefined document templates are used to define basic customization options. For greater flexibility, you can combine different document templates. For more information see Assembling documents


Before you begin…

Before starting

Before you generate any documentation, you must have a structured model in which the entry points containing the elements that are to appear in the documentation are determined.

Different types of notes describing different aspects of the element are proposed for each element. Once your model has been annotated using these notes, you can then proceed with documentation generation.

Before beginning this quick tour, the “DocumentPublisher” module must be deployed in your project by running the “Configuration/Install a module” command and selecting the “DocumentPublisher” module.

Documentation roots

Documentation generation always starts from one or several model elements, in order to generate all the elements it (they) structure(s).

Most of the time, the element concerned is a package, but it can also be a class, an actor, a use case or any other type of element according to the document template being used.


Creating a document

What is a document?

Within a Modelio model, a document is the link between the document template and the elements that are to feature in the generated documentation. Documents are used to add specific information (title, author, …) or to modify the format used. At least one document must be created before generating documentation.

How do I create a document?

2

Creating a document

The “Document creation” window then appears. In this window, you can define the generation options and the content of your document. Let’s start by defining the generation options:

3

Defining generation options for your new document

You’re now ready to define the content of your document, as shown below.

Defining the content of your new document

Note: The document creation wizard is similar to document edition.


Generating a document

Before you begin…

Before any documentation can be generated, you must have created a document and defined its properties. At least one model element must have been added, as this will act as the generation root.

How do I generate a document?

2

Generating a document

Visualizing a document

Before you begin

You can only visualize a generated document if the actual documentation generation operation has been successful. You can also choose to automatically open and view a document after every generation operation, by defining this at module parameter level.

How do I view a document?

2

Visualizing a document

Modelio Document Publisher User Guide

Introduction

General principles

Generating documentation

Advanced options