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.
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.
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
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.
Plugins dedicated to the document export into popular format will be developed.
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
No legal issues identified yet.
Relationship to other projects
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.
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.
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.
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.
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.
The following Architecture Council members will mentor this project:
- Chris Aniszczyk (Red Hat)
- Mik Kersten (Tasktop)
The following individuals, organisations, companies and projects have expressed interest in this project:
- Paul Bruno, Atos Origin
- Daniel Schaefer, Kalis
- Pierre Queinnec, Zenika
- Joël Ceyzeriat, ST-Ericsson
- Werner Keil, emergn
- December 2010 – proposal
- February 2011 - creation review and initial contribution
- March 2011 – First builds for early adopters
- June 2011 - First release aligned with Indigo
And then releases aligned with the Mylyn project schedule
Changes to this Document
|01-02-2011||Updating interested Parties and Committers|
|01-03-2011||Updating interested Parties|