A Document Publisher Template is an archive file designed and produced by the Modelio Documentation Template Editor that can be later installed in Modelio where it is used by Document Publisher to produce documentation.
The template defines which documentation contents have to be produced from the elements of the user model and how these contents are organized in the output document. The template is therefore literally driving the documentation generation process when run by the Document Publisher module to produce documentation.
Templates are one of several available techniques to produce specific documents with Document Publisher.
The Designing a template chapter details template design and introduces the concept of "node", core of Modelio documentation templates.
The First steps with the "Hello World" template chapter details a concrete example of template design and development.
The Deeper into the Template Editor chapter presents advanced concepts about node creation, and the list of all predefined nodes.
The A real example: the "Use case catalog" template chapter details step by step the content of a predefined template provided by Document Publisher.
The Extending the template editor chapter explains how predefined templates can be modified and extended.
Customizing Document Publisher documents
Modelio Document Publisher produces rich documentation from an annotated UML model. The overall and perceived quality of the produced documentation depends on several factors.
Model contents
The first factor is the quality, pertinence and quantity of the model annotations added by the user to the model. It should be obvious that a model in which no descriptions are provided for the model elements will probably result in poor documentation. This factor does not directly depend on Modelio Document Publisher but rather on the end-user.
Document contents
Not only does the model need to be properly documented, but also the way the model is browsed must be relevant. This relevance resides in the fact that the actual contents of the produced document fit the needs of the expected reader. The trick is to remember that the reader’s expectations depend…on the reader. Therefore, it is necessary to provide the right contents to the right reader. This is where templates are helpful, since they define how the model is exploited and which data is to be extracted from it.
Documentation look
Documents must be pretty (or at least perceived as such). Document Publisher uses style sheets to format the documents it produces. Customizing the used style sheet is possible.
As a direct consequence of what has been stated so far, the possibility of customizing the appearance and the contents of the produced documentation is a key feature of document generators like Modelio Document Publisher. Moreover, the exact nature of the required customization depends on specific user needs.
Modelio Document Publisher proposes five different levels of customization of the documents it produces. While the customization capabilities increase with each level, the required effort from the user and the complexity are kept minimal by Modelio which provides dedicated GUIs, tools and techniques for each level.
The five customization level
Level 1
This level is the simplest to use. It only consists in using one of the standard templates that are provided by Document Publisher. Just select a template and a couple of model elements and in just one click you get a document. The standard ‘off the shelf’ templates of Document Publisher cover most common situations in terms of reader audience and the role of the produced document in the overall application development process. Note the paradigm: one template for one document.
Level 2
Nothing very complex in level 2 which is similar to level one, being based on Document Publisher standard templates too. Here, the end-user simply changes some parameters of the chosen template. For example, the end-user can change the ‘company logo’ of the produced document, he can ask for ‘a table of contents’ section to be added to the document, place the table of contents at the top or at the end of the document and so on.
Each template comes with specific parameters which are proposed and documented in the ‘Create a document’ wizard’s GUI. Again, the one template for one document paradigm is applied.
Level 3
At level 3, Document Publisher can fit specific needs where several templates have to be combined in order to produce the right document. For example, one might need a section describing use cases, produced using the "Use case" template along with another part of the document describing the project class structure based on another template like ‘design’. Document Publisher enables templates to be combined in such cases. The result is a unique document containing the concatenated production of both templates. Note that only standard templates are used here. Moreover, no additional tooling is required, ie Modelio and its Document Publisher are all you need to benefit from all the possibilities of levels 1, 2 and 3.
Level 4
Level 4 is definitely an advanced level. It consists in designing and developing a specific template, testing it and delivering it to end-users.
Of course level 4 possibilities are huge, the first limit mainly being the template designer’s imagination. The template designer uses the Document Publisher Template Editor tool to create new templates and the important point is that no software development is required. You just have to assemble so-called "nodes" to describe what has to be done.
This is one of the main objectives of this tutorial: learn how to create a template using the template editor.
The second limit of level 4 results from the template editor possibilities, ie the standard set of nodes it features. But this limit can also be overcome… by level 5!
Level 5
Level 5 consists in extending the set of ‘nodes’ that can be used to create templates. It requires Java programming but is the most powerful means of customizing your documentation. By developing specific ‘nodes’ (a node = a couple of Java classes), you can enrich the template editor ‘dictionary’ and by assembling these custom nodes in your template you can almost create any document you might imagine.