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 :
out of scope :
The Intent project has a spirit which can be expressed with the following lines:
The Intent project is composed of the following parts:
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 :
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.
The synchronization framework is responsible for interfacing the formalism with development artifacts :
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
Tools to synchronize the formal definitions in the documentation with the development artifacts
No legal issues identified yet.
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:
We welcome additional committers and contributions.
The following Architecture Council members will mentor this project:
The following individuals, organisations, companies and projects have expressed interest in this project:
And then releases aligned with the Mylyn project schedule
|01-02-2011||Updating interested Parties and Committers|
|01-03-2011||Updating interested Parties|
Back to the top