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.
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.
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:
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.
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:
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.
When generating the document, the image is inserted at the same location as the current “description” note:
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:
When generating the document, the hyperlink is inserted instead of the image, and the label is displayed:
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.
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.
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.
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.
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 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 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 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 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:
Modelio Document Publisher is delivered as standard with a number of document templates. These document templates are available exclusively in English at this time.
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 | Packages | Overview 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. |
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.
Key:
Note: The addition of tables is currently possible only for generation in Open XML format.
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 are defined in the first tab of the document edition window, and in the first page of the document creation wizard.
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.
Key:
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.
Document: Within a Modelio model, the document is the link between document templates and the elements that will feature in documentation. A document is used to add specific information (title, author, …) or to modify the format used.
Document folder: A document folder is a section of a model designed to contain documents. However, documents can be moved elsewhere within the model.
HTML: This documentation format can be generated and viewed in UNIX and Windows. HTML documentation can be used by all web navigators.
Open XML: Format associated with the latest version of Microsoft Word. This format can only be viewed in Windows.
ODT: Format associated with Libre and Open Office suites. This format can be viewed in both Windows and Unix.
Document template: A document template describes how to obtain a document from a model. It completely determines the nature of the document produced.
Note type: All model elements (classes, attributes, associations, diagrams, …) have at least one note type that can be used to describe them. The two most commonly used note types are “summary” and “description”. These notes provide additional information on the element in question.
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:
Open XML: Available for Windows, this format corresponds to the latest version of Microsoft Word (2007).
HTML: This “universal” format, available in both UNIX and Windows, provides useful hypertext links and produces interactive and distributed documents.
ODT: Available for Windows and Unix, this format corresponds to the Libre and Open Office suites.
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.
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 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 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.
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.
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:
You’re now ready to define the content of your document, as shown below.
Note: The document creation wizard is similar to document edition.
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.
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.