Skip to main content
Jump to: navigation, search

Difference between revisions of "Gendoc/FunctionalFeatures"

(Metadata and variables)
(Integrate modifications made in the generated document)
 
(28 intermediate revisions by 9 users not shown)
Line 5: Line 5:
  
 
The context of this effort is that by mid 2015, PolarSys solutions like Papyrus and Capella have more traction, but a lot of people are asking for a means to generate doc from the models. Gendoc is our project for documentation generation, and we feel that there is a clear opportunity to collaborate inside PolarSys to improve the existing Gendoc tool and to gather other complementary doc generators under the Gendoc umbrella.
 
The context of this effort is that by mid 2015, PolarSys solutions like Papyrus and Capella have more traction, but a lot of people are asking for a means to generate doc from the models. Gendoc is our project for documentation generation, and we feel that there is a clear opportunity to collaborate inside PolarSys to improve the existing Gendoc tool and to gather other complementary doc generators under the Gendoc umbrella.
This approach was first discussed during a [[https://polarsys.org/wiki/Technical_exchange:_doc_generation teleconference on July 6th 2015]].
+
This approach was first discussed during a [https://polarsys.org/wiki/Technical_exchange:_doc_generation#July_6.2C_2015 teleconference on July 6th 2015] and completed in a [https://polarsys.org/wiki/Technical_exchange:_doc_generation#August.2C_25th_2015 teleconference on August, 25th 2015]
 +
A telco to establish commitment and work out a process for creating the backlog was held on [https://polarsys.org/wiki/Technical_exchange:_doc_generation#December.2C_12th_2015 December 12, 2015].
 +
 
 +
==Teleconferences==
 +
* [https://polarsys.org/wiki/Technical_exchange:_doc_generation#July_6.2C_2015 teleconference on July 6th 2015]
 +
* [https://polarsys.org/wiki/Technical_exchange:_doc_generation#August.2C_25th_2015 teleconference on August, 25th 2015]
 +
* [https://polarsys.org/wiki/Technical_exchange:_doc_generation#December.2C_12th_2015 teleconference on December, 12th 2015]
  
 
==Rules for this page==
 
==Rules for this page==
Line 16: Line 22:
 
==Interested parties==
 
==Interested parties==
 
* Atos
 
* Atos
 +
* Airbus
 
* Airbus Defence & Space
 
* Airbus Defence & Space
* Airbus Helicopters
 
 
* Ericsson
 
* Ericsson
 
* Obeo
 
* Obeo
 +
* Samares Engineering
 
* Thales
 
* Thales
 
* Zeligsoft
 
* Zeligsoft
Line 25: Line 32:
 
==Users==
 
==Users==
  
===Developper===
+
===Developer===
A developper is a user that is knowledgeable of the target meta models and that is a regular eclipse user.  
+
A developer is a user that is knowledgeable of the target meta models and that is a regular eclipse user.  
  
=== WordProcessor expert ===
+
===WordProcessor expert===
 
A wordprocessor expert is a user that has a detailed knowledge of a word processor (style, macros, etc.) like word or openoffice but that has few knowledge of the target meta models and few to no knowledge of software development.
 
A wordprocessor expert is a user that has a detailed knowledge of a word processor (style, macros, etc.) like word or openoffice but that has few knowledge of the target meta models and few to no knowledge of software development.
  
=== Final user ===
+
===Document owner===
The final user actually generates the documentation from a model and uses the documentation
+
The document owner actually generates the documentation from a model. S/he is the person formally responsible for delivering the generated document to the document consumers.
 +
 
 +
===Document consumer===
 +
The document consumer reads the produced document, without access to (or need for) the generation environment. Typically, this would be stakeholders like product owners, business partners and developers using other development environments.
  
 
<!-- Copy the two template lines, below, and paste them above this one and edit the copied lines, keeping the original lines intact -->
 
<!-- Copy the two template lines, below, and paste them above this one and edit the copied lines, keeping the original lines intact -->
Line 43: Line 53:
  
 
* Initially written by: Romain Guider - Obeo
 
* Initially written by: Romain Guider - Obeo
* Interested parties: Obeo (romain.guider@obeo.fr), Atos
+
* Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
* Status in Gendoc 0.5.0 : Implemented, depends on "reliable"
+
* Status in Gendoc 0.5.0 : Partially implemented, depends on "reliable". A fix should bee created for Gendoc 1.0 to support current version of MS Word.
 +
* Study to re-architecture the way to save a document to improve a long term reliability for a post-1.0 version.
  
 
===Reliable odt output ===
 
===Reliable odt output ===
Line 53: Line 64:
 
* Status in Gendoc 0.5.0 : Implemented, depends on "reliable"
 
* Status in Gendoc 0.5.0 : Implemented, depends on "reliable"
  
=== Wysiwyg editing of templates in word processor ===
+
=== Simplify the edition of templates with a less technical syntax ===
  
 
* Description: edition of templates must be done within word and word styling within the tempate code shoud be used to determine the styling of the generated document parts. The template language should be as simple as possible and the less possible verbose so that word experts can create simple templates. Capabilities of the template language should include, to start with,  
 
* Description: edition of templates must be done within word and word styling within the tempate code shoud be used to determine the styling of the generated document parts. The template language should be as simple as possible and the less possible verbose so that word experts can create simple templates. Capabilities of the template language should include, to start with,  
Line 60: Line 71:
 
** repetition of templates and value injection (both in tables and paragraphs)  for lists of objects from the target models at document generation time (equivalent of the for loop)
 
** repetition of templates and value injection (both in tables and paragraphs)  for lists of objects from the target models at document generation time (equivalent of the for loop)
 
** selection between two templates or two templates fragments based on a condition holding on model values so that document generation can accomodate diffrerent model's patterns (equivalent of the if construct)
 
** selection between two templates or two templates fragments based on a condition holding on model values so that document generation can accomodate diffrerent model's patterns (equivalent of the if construct)
** insertion of images in document from an external source (either a fixed image or an image drawn from a framework like Sirius, Papyrus or any diagram manipulation technology).  
+
** insertion of images in document from an external source (either a fixed image or an image drawn from a framework like Sirius, Papyrus or any diagram manipulation technology). Make sure that vector graphics formats are supported (especially SVG)
 +
As more as possible, existing features of native widgets of authoring tools (like images properties, styles, ...) should be prefer to technical tags.
  
 
* Initially written by: Romain Guider - Obeo
 
* Initially written by: Romain Guider - Obeo
* Interested parties: Obeo (romain.guider@obeo.fr), Atos
+
* Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
* Status in Gendoc 0.5.0 : Implemented
+
* Status in Gendoc 0.5.0 : Implemented with XML and Acceleo queries. Need analysis to simplify the existing syntax.
  
 
=== Localized error feedback ===
 
=== Localized error feedback ===
Line 71: Line 83:
  
 
* Initially written by: Romain Guider - Obeo
 
* Initially written by: Romain Guider - Obeo
* Interested parties: Obeo (romain.guider@obeo.fr), Atos
+
* Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
* Status in Gendoc 0.5.0 : To Improve
+
* Status in Gendoc 0.5.0 : To Improve. Short term: an execution trace. Long term: the most possible precise error detection in the initial template.
  
 
=== Model queries ===
 
=== Model queries ===
  
* Description: developper should be able to write simple to complex queries in the templates so that they can express complex document generation behavior (like model element filtering, string processing, etc.)
+
* Description: developer should be able to write simple to complex queries in the templates so that they can express complex document generation behavior (like model element filtering, string processing, etc.). A list of available queries should be provided in the authoring tool. Optionally: be able to call these queries from VB Macros.
  
 
* Initially written by: Romain Guider - Obeo
 
* Initially written by: Romain Guider - Obeo
* Interested parties: Obeo (romain.guider@obeo.fr), Atos
+
* Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented
 
* Status in Gendoc 0.5.0 : Implemented
  
 
=== Services call in templates ===
 
=== Services call in templates ===
  
* Description: developpers should be able to write services in Java and call them from templates so that they can keep the templates simple while expressing rich behavior. Developpers should also be able to write java services to capture complex behavior so that word experts can call them in templates.
+
* Description: developers should be able to write services in Java and call them from templates so that they can keep the templates simple while expressing rich behavior. Developers should also be able to write java services to capture complex behavior so that word experts can call them in templates.
  
 
* Initially written by: Romain Guider - Obeo
 
* Initially written by: Romain Guider - Obeo
* Interested parties: Obeo (romain.guider@obeo.fr), Atos
+
* Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented
 
* Status in Gendoc 0.5.0 : Implemented
  
Line 93: Line 105:
 
* Description: It shall be possible to insert hyperlink in the template to reference future parts of documents. Example (in UML2) in a property description set an hyperlink to the the definition of the type
 
* Description: It shall be possible to insert hyperlink in the template to reference future parts of documents. Example (in UML2) in a property description set an hyperlink to the the definition of the type
 
* Initially written by: Tristan FAURE (Atos)
 
* Initially written by: Tristan FAURE (Atos)
* Interested parties: Atos
+
* Interested parties: Atos, Airbus, Airbus D&S, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented
 
* Status in Gendoc 0.5.0 : Implemented
  
Line 99: Line 111:
 
* Description: it shall be possible to run documentation generation using command line interface. This feature shall provide the possibility to specify a template location, variables values ...
 
* Description: it shall be possible to run documentation generation using command line interface. This feature shall provide the possibility to specify a template location, variables values ...
 
* Initially written by: Tristan FAURE (Atos)  
 
* Initially written by: Tristan FAURE (Atos)  
* Interested parties: Atos
+
* Interested parties: Atos, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented
 
* Status in Gendoc 0.5.0 : Implemented
  
Line 105: Line 117:
 
* Description: it shall be possible to insert HTML content (or another rich text content) contained in the EMF models (for example documentation of an element) in the document.
 
* Description: it shall be possible to insert HTML content (or another rich text content) contained in the EMF models (for example documentation of an element) in the document.
 
* Initially written by: Tristan FAURE (Atos)
 
* Initially written by: Tristan FAURE (Atos)
* Interested parties: Atos
+
* Interested parties: Atos, Airbus, Airbus D&S, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented
 
* Status in Gendoc 0.5.0 : Implemented
  
Line 111: Line 123:
 
* Description: It shall be possible to run already defined templates contained in bundles using the graphical user interface.
 
* Description: It shall be possible to run already defined templates contained in bundles using the graphical user interface.
 
* Initially written by: Tristan FAURE (Atos)
 
* Initially written by: Tristan FAURE (Atos)
* Interested parties: Atos
+
* Interested parties: Atos, Airbus, Airbus D&S, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented
 
* Status in Gendoc 0.5.0 : Implemented
  
Line 117: Line 129:
 
* Description: It shall be possible to insert some variables and meta data in the generated document. Example of metadata : name of the generated document, time of the generation, connected user.
 
* Description: It shall be possible to insert some variables and meta data in the generated document. Example of metadata : name of the generated document, time of the generation, connected user.
 
* Initially written by: Tristan FAURE (Atos).
 
* Initially written by: Tristan FAURE (Atos).
* Interested parties: Atos.
+
* Interested parties: Atos, Airbus, Airbus D&S, Ericsson
 
* Status in Gendoc 0.5.0 : Implemented with XML tags. Need analysis to see if we can reuse existing meta-data behaviors and UI of LO and Word.
 
* Status in Gendoc 0.5.0 : Implemented with XML tags. Need analysis to see if we can reuse existing meta-data behaviors and UI of LO and Word.
 +
 +
=== Text with identations ===
 +
* Description: it shall be possible to preserve the indentations defined in the text inserted from the EMF models (for example source code from an OCL expression) in the document.
 +
* Initially written by: Yves BERNARD (Airbus).
 +
* Interested parties: Airbus, Ericsson
 +
* Status in Gendoc 0.5.0 : Implemented
 +
 +
=== Re-entering fragments ===
 +
* Description: Callable parts of a template (i.e. "fragments") shall have the ability to call themselves directly or indirectly.
 +
 +
* Initially written by: Yves BERNARD (Airbus).
 +
* Interested parties: Airbus.
 +
 +
=== Gendoc and other Eclipse Frameworks ===
 +
* Description: Gendoc should be ported to work with RMF Requirements Models to generate operational concept and specification documents, compliance summaries, traceability matrices, etc.. Ideally, gendoc should be able to work with multiple models and frameworks such as RMF, EMF, EPF et al.
 +
* Initially written by: Mannarino Systems and Software and ISO JTC1/SC7/WG24, Ronald Houde.
 +
* Interested parties: Atos
 +
* Status in Gendoc 0.5.0 : partially implemented (to improve : by providing libraries)
 +
 +
=== Gendoc Trace/debug mode ===
 +
* Description: it shall be possible to enable a "Trace" mode that would give a lot of information concerning document generation including queries processing, context...
 +
* Initially written by: Raphaël Faudou (Samares Engineering)
 +
* Interested parties: Samares Engineering, Atos, Airbus
 +
* Status in Gendoc 0.5.0 : partially implemented (to improve)
 +
 +
=== Integration with content management systems ===
 +
* Description: it shall be possible to generate document metadata reflecting the revision date of th eunderlying model(s). This metadata is then picked up by the responsible content management system.
 +
* Initially written by: Ulf Olsson (Ericsson)
 +
* Interested parties: Ericsson, Atos, Airbus
 +
 +
=== Integrate modifications made in the generated document ===
 +
* Description: it shall be possible re integrate in the model some modifications made in the document.
 +
* Initially written by: Tristan Faure, Atos
 +
* Interested parties: Atos, Airbus
  
 
<!-- Copy the three template lines, below, and paste them above this one and edit the copied lines, keeping the original lines intact -->
 
<!-- Copy the three template lines, below, and paste them above this one and edit the copied lines, keeping the original lines intact -->

Latest revision as of 02:11, 16 December 2015

Introduction and context

This page will list the functional features needed for documentation generation along with the typical users ("actors") of these features.

It is not a roadmap and the fact that a feature appears here is does not imply that it is under development or even that it should be developed soon.

The context of this effort is that by mid 2015, PolarSys solutions like Papyrus and Capella have more traction, but a lot of people are asking for a means to generate doc from the models. Gendoc is our project for documentation generation, and we feel that there is a clear opportunity to collaborate inside PolarSys to improve the existing Gendoc tool and to gather other complementary doc generators under the Gendoc umbrella. This approach was first discussed during a teleconference on July 6th 2015 and completed in a teleconference on August, 25th 2015 A telco to establish commitment and work out a process for creating the backlog was held on December 12, 2015.

Teleconferences

Rules for this page

As indicated above, the fact that a feature is listed on this page does not imply that it is under implementation or that the project committers and contributors are working on it.

The idea here is to list Gendoc features and, for each, their typical user(s), and interested parties.

Please add features description at the end of the list, and keep this template as the very last item of the list. This is best accomplished by editing the relevant main topics, i.e., "Users" or "Features" and not the templates, i.e., "User Name" or "Feature Name".

Interested parties

  • Atos
  • Airbus
  • Airbus Defence & Space
  • Ericsson
  • Obeo
  • Samares Engineering
  • Thales
  • Zeligsoft

Users

Developer

A developer is a user that is knowledgeable of the target meta models and that is a regular eclipse user.

WordProcessor expert

A wordprocessor expert is a user that has a detailed knowledge of a word processor (style, macros, etc.) like word or openoffice but that has few knowledge of the target meta models and few to no knowledge of software development.

Document owner

The document owner actually generates the documentation from a model. S/he is the person formally responsible for delivering the generated document to the document consumers.

Document consumer

The document consumer reads the produced document, without access to (or need for) the generation environment. Typically, this would be stakeholders like product owners, business partners and developers using other development environments.

User Name

  • Description of user, which could include any or all of: job title, responsibilities, education/training, tool expertise, work experience, domain expertise, etc.

Features

Reliable docx output

  • Description: the gendoc system must produce a reliable docx output from a docx template and an Ecore model. The ouput must conform to docx File Format (c.f. [MS-DOCX]: Word Extensions to the Office Open XML (.docx) File Format.) and must be robust to word version changes as long as the version supports the docx format.
  • Initially written by: Romain Guider - Obeo
  • Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Partially implemented, depends on "reliable". A fix should bee created for Gendoc 1.0 to support current version of MS Word.
  • Study to re-architecture the way to save a document to improve a long term reliability for a post-1.0 version.

Reliable odt output

  • Description: the gendoc system must produce a reliable odt output from a odt template and an Ecore model. The ouput must conform to odt File Format (c.f. [OpenDocument]: Word Extensions to the Libre/Open Office Open Document (.odt) File Format.) and must be robust to open document version changes as long as the version supports the odt format.
  • Initially written by: Tristan Faure - Atos
  • Interested parties: Atos, Airbus
  • Status in Gendoc 0.5.0 : Implemented, depends on "reliable"

Simplify the edition of templates with a less technical syntax

  • Description: edition of templates must be done within word and word styling within the tempate code shoud be used to determine the styling of the generated document parts. The template language should be as simple as possible and the less possible verbose so that word experts can create simple templates. Capabilities of the template language should include, to start with,
    • injection of values in a paragraph from the target models at document generation time
    • injection of values in a table from the target models at document generation time
    • repetition of templates and value injection (both in tables and paragraphs) for lists of objects from the target models at document generation time (equivalent of the for loop)
    • selection between two templates or two templates fragments based on a condition holding on model values so that document generation can accomodate diffrerent model's patterns (equivalent of the if construct)
    • insertion of images in document from an external source (either a fixed image or an image drawn from a framework like Sirius, Papyrus or any diagram manipulation technology). Make sure that vector graphics formats are supported (especially SVG)

As more as possible, existing features of native widgets of authoring tools (like images properties, styles, ...) should be prefer to technical tags.

  • Initially written by: Romain Guider - Obeo
  • Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented with XML and Acceleo queries. Need analysis to simplify the existing syntax.

Localized error feedback

  • Description: syntax errors in templates and references to unknown meta model concepts (EClasses) and features should be reported in such a way that the localization of the error in the word template is immediate. Localization of errors must point to the word paragraph (possibly template's page and line) where it lies and provide as much detail as possible on the error so that the developper can correct errors in an efficient manner.
  • Initially written by: Romain Guider - Obeo
  • Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : To Improve. Short term: an execution trace. Long term: the most possible precise error detection in the initial template.

Model queries

  • Description: developer should be able to write simple to complex queries in the templates so that they can express complex document generation behavior (like model element filtering, string processing, etc.). A list of available queries should be provided in the authoring tool. Optionally: be able to call these queries from VB Macros.
  • Initially written by: Romain Guider - Obeo
  • Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Services call in templates

  • Description: developers should be able to write services in Java and call them from templates so that they can keep the templates simple while expressing rich behavior. Developers should also be able to write java services to capture complex behavior so that word experts can call them in templates.
  • Initially written by: Romain Guider - Obeo
  • Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Hyperlinks

  • Description: It shall be possible to insert hyperlink in the template to reference future parts of documents. Example (in UML2) in a property description set an hyperlink to the the definition of the type
  • Initially written by: Tristan FAURE (Atos)
  • Interested parties: Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Command Line Interface

  • Description: it shall be possible to run documentation generation using command line interface. This feature shall provide the possibility to specify a template location, variables values ...
  • Initially written by: Tristan FAURE (Atos)
  • Interested parties: Atos, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Rich Text

  • Description: it shall be possible to insert HTML content (or another rich text content) contained in the EMF models (for example documentation of an element) in the document.
  • Initially written by: Tristan FAURE (Atos)
  • Interested parties: Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Wizards

  • Description: It shall be possible to run already defined templates contained in bundles using the graphical user interface.
  • Initially written by: Tristan FAURE (Atos)
  • Interested parties: Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Metadata and variables

  • Description: It shall be possible to insert some variables and meta data in the generated document. Example of metadata : name of the generated document, time of the generation, connected user.
  • Initially written by: Tristan FAURE (Atos).
  • Interested parties: Atos, Airbus, Airbus D&S, Ericsson
  • Status in Gendoc 0.5.0 : Implemented with XML tags. Need analysis to see if we can reuse existing meta-data behaviors and UI of LO and Word.

Text with identations

  • Description: it shall be possible to preserve the indentations defined in the text inserted from the EMF models (for example source code from an OCL expression) in the document.
  • Initially written by: Yves BERNARD (Airbus).
  • Interested parties: Airbus, Ericsson
  • Status in Gendoc 0.5.0 : Implemented

Re-entering fragments

  • Description: Callable parts of a template (i.e. "fragments") shall have the ability to call themselves directly or indirectly.
  • Initially written by: Yves BERNARD (Airbus).
  • Interested parties: Airbus.

Gendoc and other Eclipse Frameworks

  • Description: Gendoc should be ported to work with RMF Requirements Models to generate operational concept and specification documents, compliance summaries, traceability matrices, etc.. Ideally, gendoc should be able to work with multiple models and frameworks such as RMF, EMF, EPF et al.
  • Initially written by: Mannarino Systems and Software and ISO JTC1/SC7/WG24, Ronald Houde.
  • Interested parties: Atos
  • Status in Gendoc 0.5.0 : partially implemented (to improve : by providing libraries)

Gendoc Trace/debug mode

  • Description: it shall be possible to enable a "Trace" mode that would give a lot of information concerning document generation including queries processing, context...
  • Initially written by: Raphaël Faudou (Samares Engineering)
  • Interested parties: Samares Engineering, Atos, Airbus
  • Status in Gendoc 0.5.0 : partially implemented (to improve)

Integration with content management systems

  • Description: it shall be possible to generate document metadata reflecting the revision date of th eunderlying model(s). This metadata is then picked up by the responsible content management system.
  • Initially written by: Ulf Olsson (Ericsson)
  • Interested parties: Ericsson, Atos, Airbus

Integrate modifications made in the generated document

  • Description: it shall be possible re integrate in the model some modifications made in the document.
  • Initially written by: Tristan Faure, Atos
  • Interested parties: Atos, Airbus


Feature Name

  • Description: this is a template to describe new features. Please add features at the end of the list, and keep this template as the very last item of the list.
  • Initially written by: add the company and name of the person who added this feature description.
  • Interested parties: Please add company and contact name if your company would use this feature.

Back to the top