Mylyn Intent

The project has been created.

Mylyn Intent

The Intent project is a proposed open-source project under the
Mylyn/Docs project.

This proposal is in the Project Proposal Phase (as defined in
the Eclipse Development Process) and is written to declare its
intent and scope. We solicit additional participation and input
from the Eclipse community. Please send all feedbacks to the
Eclipse
Proposal Forum.

Background

The Eclipse IDE is used to provide the best environment to
write and test code. Since the creation of the Mylyn project, a
complete set of projects are now providing proper integration for
all the other tasks a developer needs to do in his daily job :
from the versions management to the builds, while going through
the defects and tasks. Another critical aspect of the application
life-cycle is the management of the knowledge concerning the
application : its design choices and the intention behind these
choices. Documentation is used to capture this knowledge, but
keeping this documentation in sync with the reality is a constant
effort.

Donald E. Knuth proposed a solution to this exact problem for
software through the definition of «Literate
Programming» : a language mixing documentation and code.
Even if this approach looked appealing, it could not fit with the
industry practices, adding too much burden, especially with code
which is inherently operational.

That said, providing such an approach in a more flexible way
on top of models (which are inherently declaratives) is a
promising way to help developers to provide useful documentation
and to keep it up-to-date. Furthermore, integrating it directly
in the IDE lowers the barrier of the documentation update and
will allow cross-references with development artifacts.

Let’s take an example : a developer describes the
general architecture in his documentation describing its OSGi
modules, their id and dependencies and the reasons
why the system has been designed this way. These
instructions are part of the doc and are compared, when the doc
gets validated, with the informations provided by the PDE in this
regard. Any inconsistent state leads to problem markers with
associated quick fixes to either update the doc or the
bundles.

Scope

This project is focused on providing an editing environment to
author documentations mixing natural and formal language, easing
the application life-cycle management by capturing the
intents and design choices made during development.

Specific integration will be provided with existing Eclipse
projects to retrieve and synchronize the development artifacts
with the formal descriptions. The Intent project will focus on
providing an extensible framework and actively solicit
contributions in this regard.

in scope :

Tools for creating documentation mixing a formal
and non-formal syntax

Tools for collaborating on top of such documentations

Tools for editing, validating the documentation

Tools for synchronizing the documentation regarding the
development artifacts

out of scope :

Tooling and framework to create domain specific
languages

Specific support for documentation formats and syntaxes
(see wikitext).

Reusable UI components for documentation or rich text
editing.

Documentation file format interoperability

Description

The Intent project has a spirit which can be expressed with
the following lines:

doc versus code versus model : they are all equals : you
can start writing code and synchronize your doc or writing doc
and synchronize your artifacts, just use the right tool for the
task.

writing and maintaining doc should be useful, easy and
fun

the documentation will gain value by its integration with
other Eclipse projects

lowering the barrier : nice tooling with appealing and well
integrated user interface

The Intent project is composed of the following parts:

A documentation language

A language mixing the wiki syntax from wikitext with a syntax
dedicated to the definition of model fragments. This can be seen
as a literate modeling (like in literate
programming) documentation language, having the ability to
:

organize the design of the system as a document, keeping in
mind the targeted audience and not the constraints coming from
the development artifacts ;

split the definition of formal elements among several
sections or chapters, according to the need they allow to
answer to.

An authoring tooling:

A complete IDE providing wizards, editors with syntax
highlighting and code completion for the documentation language.
Validation of the formal elements description will be fully
integrated to this IDE.

A synchronization
framework

The synchronization framework is responsible for interfacing
the formalism with development artifacts :

it compiles the document into complete models upon which
constraints and predicates can be checked ;

it synchronizes these models with the real development
artifacts providing the user two possibilities : updating the
documentation or updating the artifact itself ;

it has the ability to be extended to provide better
integration with other Eclipse projects, enabling for instance
consistency check between PDE artifacts and the
documentation.

Output generators

Plugins dedicated to the document export into popular format
will be developed.

Initial Contribution

The below is the consolidated vision of the contributing
companies about the initial contribution of the project.

Tools to author documentation mixing formal and natural
languages

an Eclipse IDE Editor

Wizards and UI to create and manage documentation
projects.

Tools to synchronize the formal definitions in the
documentation with the development artifacts

a document constraints checker

a generic synchronizer for any EMF model

an indexer service for the documentation

Legal Issues

No legal issues identified yet.

Relationship to other
projects

Wikitext

The proposed project re-uses the wikitext component as a basis
of the documentation syntax. Both projects will feed each others
as Intent might have specific needs that could be fulfilled with
the corresponding contributions in wikitext. We are confident
that by sharing the same Mylyn/Docs umbrella project
collaboration will be constant and efficient.

TMF/Xtext

The Intent project does not aim to compete with the Textual
Modeling Framework projects, the goal is not to provide specific
textual syntaxes nor to provide a framework to create them though
allowing model description through a generic textual syntax and
providing extension points to plug dedicated syntaxes which might
be defined with the help of Xtext.

EMF

The formal definitions integrated in the doc will be based on
EMF core and the synchronization between doc-expected
versus development artifact will leverage the EMF Compare
component. Intent also depends on the EMF CDO
project, used here to provide a strong support to concurrency in
the core services.

Doc2Model

The Intent project does not aim to provide any framework
easing the parsing or reverse-engineering of documentation to
build a model and as such is not overlapping with the doc2model
project focus.

Legal Issues

Committers

The following individuals are proposed as initial committers to the project:

Alex Lagarde project lead, Obeo

Alex initiated the project and implemented the initial contribution.

Cedric Brun, Obeo

Cedric participated in the design and development of the initial contribution, as the Compare lead he will work on the artifacts synchronizer.

Fabian Steeg, University of Cologne

Fabian is interested in the literate modeling approach and is interested in integrating Zest and Intent.

Eike Stepper, ES Consulting

Eike is interested in reviewing and providing help in the usage of the CDO project which brings concurrency to Intent.

William Piers, Obeo

William has developed and industrialized the M2M/Atlas Transformation Language (ATL) project. His experience will be useful for developing an efficient and usable tool, and for providing support to the community.

We welcome additional committers and contributions.

Mentors

The following Architecture Council members will mentor this
project:

Chris Aniszczyk (Red Hat)

Mik Kersten (Tasktop)

Interested Parties

The following individuals, organisations, companies and projects have
expressed interest in this project: