Skip to content

MDD Sources and processes

Jump to bottom
knjetl edited this page Dec 2, 2021 · 15 revisions

Overview

Documentation part UML (EA Documentation templates, ShapeChange, Derive from XMI ...) Written text (MS Word, AsciiDoc etc) Other
Normative references A list of normative references based on dependencies in the UML model can be exported from EA. Manual editing may be required in addition. Some standards have normative references that cannot be expressed in UML.
Terms and definitions Written text with new defintitions Existing definitions could possibly be exported from Geolexica
Conformance Can be modelled in UML (Extended 19105 model) Manual editing may be required in addition
Model documentation Derived from UML May need manual editing for combining with supporting documentation
Normative statements Can be modelled in UML (Extended 19105 model) Manual editing may be required in addition for combining with model documentation and supporting documentation
Supporting documentation May need to be combined with derived documentation
Abstract test suite Can be modelled in UML (Extended 19105 model) Manual editing may be required in addition

General remarks

A great deal of information can be stored and derived from Enterprise Architect. However, there are key points to consider:

  • It is recommended to not put information into the UML model that can be more easily maintained elsewhere, or to try to use UML outside of its purpose. EA is a UML tool, not a word-processing tool.
  • A balance must be maintained between the effort put into automated documentation and the output achieved. If deriving parts of the documentation from the model become too complicated, it may not be worth doing it automatically.
  • Automation that depends heavily on specific EA functionality or EA's XMI implementation should be avoided to the extent possible, in order to be more technology agnostic.
  • Early involvement with project teams is essential for implementation of MDD as a way of working. It is important to educate teams on the requirements and working processes.
  • TODO: Describe the model requirements and the documentation process. Update the existing documentation (https://github.com/ISO-TC211/UML-Best-Practices/wiki/DocumentationOfUmlModels) & https://github.com/ISO-TC211/UML-Best-Practices/blob/master/DocumentationOfUMLModels/Automatic%20generation%20of%20documentation%20from%20UML%20models.docx based on findings from this group. Github only, not Word document.

Normative references

The clause on normative references contains a formatted list of standards that the document in question have a normative reference to.

Source and processing

  • A list of normative references based on dependencies in the UML model can be exported from EA. As a script that summarizes per main standards package in the HM, as an EA report, or Metanorma could extract the information from the UML model.
  • Manual editing will be required to some extent. Some standards have normative references that cannot be expressed in UML.

CityGML: Written manually

TODOs

  • Develop scripts for documenting references in the HM

Terms and definitions

The clause on terms and definitions contains a formatted list of terms that are relevant for the document in question. The terms can be defined in the official ISO/TC 211 Term repository (MLGT), in other sources, or defined by the document in question.

Source and processing

Could the list of existing terms relevant for a specific standard be generated automatically? Based on an analysis of the terms used in the document. TMG/Ribose plan to implement a vocabulary service for Geolexica that may be used.

CityGML: Written manually

Conformance and abstract test suite

The clauses on conformance and abstract test suite contain tables and/or lists of conformance classes and tests for evaluation. There is a close relationship between conformance and normative statements.

Source and processing

Questions

How should conformance classes and tests be prepared?

We cannot expect everyone to know XML or AsciiDoc editing

Normative statements

Need to develop a conceptual model for requirements, recommendations, permissions. Ref https://github.com/orgs/ISO-TC211/teams/adhoc-automated-documentation/discussions/5

The terminology in the model needs to be according to the ISO terminology. The OGC model differs from the ISO terminology.

Questions/discussions:

TODOs

  • Develop the conceptual model

Model documentation

The model documentation is the main outcome of the UML model, with two main parts:

  • Summary tables
  • Data dictionary

Source and processing

The source is the UML model. The documentation can be exported as reports based on EA templates, or Metanorma can link into XMI files. Further processing in Metanorma, Word, AsciiDoc

CityGML: Exported with EA templates (RTF) + copy-paste into the main document. Worked fine. Not direct links as illustrated for Metanorma in https://github.com/ISO-TC211/AutomatedDocumentation/blob/master/Documentation%20tools/20200820-iso-tc211-model-based-authoring.pdf?

Other solutions:

TODO: Ribose will test Metanorma for deriving the CityGML documentation, and compare with the current documentation.

Questions

  • How to combine with written text? CityGML: Copy-paste. Save as AsciiDoc for inclusion in the final document.
  • Order of packages and elements? CityGML: Came out alphabetically, manual editing.

Supporting documentation

Not every aspect of a standard is fit for describing in UML. In general, extra documentation will be needed. Additional documentation may be written in AsciiDoc, Word or other tools and combined with the derived model documentation. See also opportunities in EA for linking to written text: https://github.com/orgs/ISO-TC211/teams/adhoc-automated-documentation/discussions/7/comments/2

Clone this wiki locally