mylyn.docs.intent/proposal.html - www.eclipse.org/proposals - Git at Google

 <!--
 	This document is provided as a template along with some guidance for creating
 	your project proposal. This is just a template. Feel free to change it as
 	you see fit (add sections, remove section). We feel, however, that the
 	suggestions represented in this document represent the reasonable minimum
 	amount of information to move forward.

 	Please keep the formatting in this document simple. Please do not edit
 	this document in Microsoft Word as it adds huge piles of markup that make
 	it difficult to restyle.

 	More information is available here:

 	http://wiki.eclipse.org/Development_Resources/HOWTO/Pre-Proposal_Phase

 	Direct any questions about this template to emo@eclipse.org
  -->

 <html>
 <head>
   <meta http-equiv="Content-Type" content=
   "text/html; charset=us-ascii" />
 <!--
 	Include the title here. We will parse it out of here and include it on the
 	rendered webpage. Do not duplicate the title within the text of your page.
  -->

 <title>Mylyn Intent</title>
 </head>

 <!--
 	We make use of the 'classic' HTML Definition List (dl) tag to specify
 	committers. I know... you haven't seen this tag in a long while...
  -->

 <style>
 dt {
 display: list-item;
 list-style-position:outside;
 list-style-image:url(/eclipse.org-common/themes/Phoenix/images/arrow.gif);
 margin-left:16px;
 }
 dd {
 margin-left:25px;
 margin-bottom:5px;
 }
 </style>

 <body>

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

   <p>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
   <a href="http://www.eclipse.org/forums/eclipse.proposals">Eclipse
   Proposal</a> Forum.</p>

   <h2 id="Background">Background</h2>

   <p>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.</p>

   <p>Donald E. Knuth proposed a solution to this exact problem for
   software through the definition of &laquo;Literate
   Programming&raquo; : 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.</p>

   <p>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.</p>

   <p>Let&rsquo;s take an example : a developer describes the
   general architecture in his documentation describing its OSGi
   modules, their id and dependencies and <strong>the reasons
   why</strong> 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.</p>

   <h2 id="Scope">Scope</h2>

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

   <p>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.</p>

   <p>in scope :</p>

   <ul>
     <li>Tools for creating documentation <strong>mixing a formal
     and non-formal syntax</strong></li>

     <li>Tools for collaborating on top of such documentations</li>

     <li>Tools for editing, validating the documentation</li>

     <li>Tools for synchronizing the documentation regarding the
     development artifacts</li>
   </ul>

   <p>out of scope :</p>

   <ul>
     <li>Tooling and framework to create domain specific
     languages</li>

     <li>Specific support for documentation formats and syntaxes
     (see <strong>wikitext</strong>).</li>

     <li>Reusable UI components for documentation or rich text
     editing.</li>

     <li>Documentation file format interoperability</li>
   </ul>

   <h2 id="Description">Description</h2>

   <p>The Intent project has a spirit which can be expressed with
   the following lines:</p>

   <ul>
     <li>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.</li>

     <li>writing and maintaining doc should be useful, easy and
     fun</li>

     <li>the documentation will gain value by its integration with
     other Eclipse projects</li>

     <li>lowering the barrier : nice tooling with appealing and well
     integrated user interface</li>
   </ul>

   <p>The Intent project is composed of the following parts:</p>

   <h3 id="Adocumentationlanguage">A documentation language</h3>

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

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

     <li>split the definition of formal elements among several
     sections or chapters, according to the need they allow to
     answer to.</li>
   </ul>

   <h3 id="Anauthoringtooling">An authoring tooling:</h3>

   <p>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.</p>

   <h3 id="Asynchronizationframework">A synchronization
   framework</h3>

   <p>The synchronization framework is responsible for interfacing
   the formalism with development artifacts :</p>

   <ul>
     <li>it compiles the document into complete models upon which
     constraints and predicates can be checked ;</li>

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

     <li>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.</li>
   </ul>

   <h3 id="Outputgenerators">Output generators</h3>

   <p>Plugins dedicated to the document export into popular format
   will be developed.</p>

   <h2 id="InitialContribution">Initial Contribution</h2>

   <p>The below is the consolidated vision of the contributing
   companies about the initial contribution of the project.</p>

   <p>Tools to author documentation mixing formal and natural
   languages</p>

   <ul>
     <li>an Eclipse IDE Editor</li>

     <li>Wizards and UI to create and manage documentation
     projects.</li>
   </ul>

   <p>Tools to synchronize the formal definitions in the
   documentation with the development artifacts</p>

   <ul>
     <li>a document constraints checker</li>

     <li>a generic synchronizer for any EMF model</li>

     <li>an indexer service for the documentation</li>
   </ul>

   <h2 id="LegalIssues">Legal Issues</h2>

   <p>No legal issues identified yet.</p>

   <h2 id="Relationshiptootherprojects">Relationship to other
   projects</h2>

   <h3 id="Wikitext">Wikitext</h3>

   <p>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.</p>

   <h3 id="TMFXtext">TMF/Xtext</h3>

   <p>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.</p>

   <h3 id="EMF">EMF</h3>

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

   <h3 id="Doc2Model">Doc2Model</h3>

   <p>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.</p>


 <!--
 	Describe any existing code that will be contributed to the project.
  -->

 <h2>Legal Issues</h2>

 <!--
 	Please describe any potential legal issues in this section. Does somebody else
 	own the trademark to the project name? Is there some issue that prevents you
 	from licensing the project under the Eclipse Public License? Are parts of the
 	code available under some other license? Are there any LGPL/GPL bits that you
 	absolutely require?
  -->

 <h2>Committers</h2>


 <!--
 	List any initial committers that should be provisioned along with the
 	new project. Include affiliation, but do not include email addresses at
 	this point.
  -->


 <p>The following individuals are proposed as initial committers to the project:</p>

 <dl>
 	<dt>Alex Lagarde project lead, Obeo</dt>
 	<dd>Alex initiated the project and implemented the initial contribution.</dd>
 	<dt>Cedric Brun, Obeo</dt>
 	<dd>Cedric participated in the design and development of the initial contribution, as the Compare lead he will work on the artifacts synchronizer.</dd>
 	<dt>Fabian Steeg, University of Cologne</dt>
 	<dd>Fabian is interested in the literate modeling approach and is interested in integrating Zest and Intent.
 	<dt>Eike Stepper, ES Consulting</dt>
 	<dd>Eike is interested in reviewing and providing help in the usage of the CDO project which brings concurrency to Intent.
 	</dd>
 	<dt>William Piers, Obeo</dt>
 	<dd>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.
 	</dd>
 </dl>

 <p>We welcome additional committers and contributions.</p>


 <h2>Mentors</h2>

 <!--
 	New Eclipse projects require a minimum of two mentors from the Architecture
 	Council. You need to identify two mentors before the project is created. The
 	proposal can be posted before this section is filled in (it's a little easier
 	to find a mentor when the proposal itself is public).
  -->

 <p>The following Architecture Council members will mentor this
 project:</p>

 <ul>
 	<li>Chris Aniszczyk (Red Hat)</li>
 	<li>Mik Kersten (Tasktop)</li>
 </ul>

 <h2>Interested Parties</h2>

 <!--
 	Provide a list of individuals, organisations, companies, and other Eclipse
 	projects that are interested in this project. This list will provide some
 	insight into who your project's community will ultimately include. Where
 	possible, include affiliations. Do not include email addresses.
  -->

 <p>The following individuals, organisations, companies and projects have
 expressed interest in this project:</p>

 <ul>
   <li>Paul Bruno, Atos Origin</li>
   <li>Daniel Schaefer, Kalis</li>
   <li>Pierre Queinnec, Zenika</li>
   <li>Jo&#235;l Ceyzeriat, ST-Ericsson</li>
   <li>Werner Keil, emergn</li>
 </ul>

 <h2>Project Scheduling</h2>

   <ul>
     <li>December 2010 &ndash; proposal</li>

     <li>February 2011 - creation review and initial
     contribution</li>

     <li>March 2011 &ndash; First builds for early adopters</li>

     <li>June 2011 - First release aligned with Indigo</li>
   </ul>

   <p>And then releases aligned with the Mylyn project schedule</p>


 <h2>Changes to this Document</h2>

 <!--
 	List any changes that have occurred in the document here.
 	You only need to document changes that have occurred after the document
 	has been posted live for the community to view and comment.
  -->

 <table>
 	<tr>
 		<th>Date</th>
 		<th>Change</th>
 	</tr>
 	<tr>
 		<td>14-12-2010</td>
 		<td>Document created</td>
 	</tr>
 		<tr>
 		<td>01-02-2011</td>
 		<td>Updating interested Parties and Committers</td>
 	</tr>
 		</tr>
 		<tr>
 		<td>01-03-2011</td>
 		<td>Updating interested Parties</td>
 	</tr>
 </table>
 </body>
 </html>
	<!--
	This document is provided as a template along with some guidance for creating
	your project proposal. This is just a template. Feel free to change it as
	you see fit (add sections, remove section). We feel, however, that the
	suggestions represented in this document represent the reasonable minimum
	amount of information to move forward.

	Please keep the formatting in this document simple. Please do not edit
	this document in Microsoft Word as it adds huge piles of markup that make
	it difficult to restyle.

	More information is available here:

	http://wiki.eclipse.org/Development_Resources/HOWTO/Pre-Proposal_Phase

	Direct any questions about this template to emo@eclipse.org
	-->

	<html>
	<head>
	<meta http-equiv="Content-Type" content=
	"text/html; charset=us-ascii" />
	<!--
	Include the title here. We will parse it out of here and include it on the
	rendered webpage. Do not duplicate the title within the text of your page.
	-->

	<title>Mylyn Intent</title>
	</head>

	<!--
	We make use of the 'classic' HTML Definition List (dl) tag to specify
	committers. I know... you haven't seen this tag in a long while...
	-->

	<style>
	dt {
	display: list-item;
	list-style-position:outside;
	list-style-image:url(/eclipse.org-common/themes/Phoenix/images/arrow.gif);
	margin-left:16px;
	}
	dd {
	margin-left:25px;
	margin-bottom:5px;
	}
	</style>

	<body>

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

	<p>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
	<a href="http://www.eclipse.org/forums/eclipse.proposals">Eclipse
	Proposal</a> Forum.</p>

	<h2 id="Background">Background</h2>

	<p>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.</p>

	<p>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.</p>

	<p>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.</p>

	<p>Let’s take an example : a developer describes the
	general architecture in his documentation describing its OSGi
	modules, their id and dependencies and <strong>the reasons
	why</strong> 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.</p>

	<h2 id="Scope">Scope</h2>

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

	<p>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.</p>

	<p>in scope :</p>

	<ul>
	<li>Tools for creating documentation <strong>mixing a formal
	and non-formal syntax</strong></li>

	<li>Tools for collaborating on top of such documentations</li>

	<li>Tools for editing, validating the documentation</li>

	<li>Tools for synchronizing the documentation regarding the
	development artifacts</li>
	</ul>

	<p>out of scope :</p>

	<ul>
	<li>Tooling and framework to create domain specific
	languages</li>

	<li>Specific support for documentation formats and syntaxes
	(see <strong>wikitext</strong>).</li>

	<li>Reusable UI components for documentation or rich text
	editing.</li>

	<li>Documentation file format interoperability</li>
	</ul>

	<h2 id="Description">Description</h2>

	<p>The Intent project has a spirit which can be expressed with
	the following lines:</p>

	<ul>
	<li>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.</li>

	<li>writing and maintaining doc should be useful, easy and
	fun</li>

	<li>the documentation will gain value by its integration with
	other Eclipse projects</li>

	<li>lowering the barrier : nice tooling with appealing and well
	integrated user interface</li>
	</ul>

	<p>The Intent project is composed of the following parts:</p>

	<h3 id="Adocumentationlanguage">A documentation language</h3>

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

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

	<li>split the definition of formal elements among several
	sections or chapters, according to the need they allow to
	answer to.</li>
	</ul>

	<h3 id="Anauthoringtooling">An authoring tooling:</h3>

	<p>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.</p>

	<h3 id="Asynchronizationframework">A synchronization
	framework</h3>

	<p>The synchronization framework is responsible for interfacing
	the formalism with development artifacts :</p>

	<ul>
	<li>it compiles the document into complete models upon which
	constraints and predicates can be checked ;</li>

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

	<li>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.</li>
	</ul>

	<h3 id="Outputgenerators">Output generators</h3>

	<p>Plugins dedicated to the document export into popular format
	will be developed.</p>

	<h2 id="InitialContribution">Initial Contribution</h2>

	<p>The below is the consolidated vision of the contributing
	companies about the initial contribution of the project.</p>

	<p>Tools to author documentation mixing formal and natural
	languages</p>

	<ul>
	<li>an Eclipse IDE Editor</li>

	<li>Wizards and UI to create and manage documentation
	projects.</li>
	</ul>

	<p>Tools to synchronize the formal definitions in the
	documentation with the development artifacts</p>

	<ul>
	<li>a document constraints checker</li>

	<li>a generic synchronizer for any EMF model</li>

	<li>an indexer service for the documentation</li>
	</ul>

	<h2 id="LegalIssues">Legal Issues</h2>

	<p>No legal issues identified yet.</p>

	<h2 id="Relationshiptootherprojects">Relationship to other
	projects</h2>

	<h3 id="Wikitext">Wikitext</h3>

	<p>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.</p>

	<h3 id="TMFXtext">TMF/Xtext</h3>

	<p>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.</p>

	<h3 id="EMF">EMF</h3>

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

	<h3 id="Doc2Model">Doc2Model</h3>

	<p>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.</p>


	<!--
	Describe any existing code that will be contributed to the project.
	-->

	<h2>Legal Issues</h2>

	<!--
	Please describe any potential legal issues in this section. Does somebody else
	own the trademark to the project name? Is there some issue that prevents you
	from licensing the project under the Eclipse Public License? Are parts of the
	code available under some other license? Are there any LGPL/GPL bits that you
	absolutely require?
	-->

	<h2>Committers</h2>


	<!--
	List any initial committers that should be provisioned along with the
	new project. Include affiliation, but do not include email addresses at
	this point.
	-->



	<p>The following individuals are proposed as initial committers to the project:</p>

	<dl>
	<dt>Alex Lagarde project lead, Obeo</dt>
	<dd>Alex initiated the project and implemented the initial contribution.</dd>
	<dt>Cedric Brun, Obeo</dt>
	<dd>Cedric participated in the design and development of the initial contribution, as the Compare lead he will work on the artifacts synchronizer.</dd>
	<dt>Fabian Steeg, University of Cologne</dt>
	<dd>Fabian is interested in the literate modeling approach and is interested in integrating Zest and Intent.
	<dt>Eike Stepper, ES Consulting</dt>
	<dd>Eike is interested in reviewing and providing help in the usage of the CDO project which brings concurrency to Intent.
	</dd>
	<dt>William Piers, Obeo</dt>
	<dd>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.
	</dd>
	</dl>

	<p>We welcome additional committers and contributions.</p>


	<h2>Mentors</h2>

	<!--
	New Eclipse projects require a minimum of two mentors from the Architecture
	Council. You need to identify two mentors before the project is created. The
	proposal can be posted before this section is filled in (it's a little easier
	to find a mentor when the proposal itself is public).
	-->

	<p>The following Architecture Council members will mentor this
	project:</p>

	<ul>
	<li>Chris Aniszczyk (Red Hat)</li>
	<li>Mik Kersten (Tasktop)</li>
	</ul>

	<h2>Interested Parties</h2>

	<!--
	Provide a list of individuals, organisations, companies, and other Eclipse
	projects that are interested in this project. This list will provide some
	insight into who your project's community will ultimately include. Where
	possible, include affiliations. Do not include email addresses.
	-->

	<p>The following individuals, organisations, companies and projects have
	expressed interest in this project:</p>

	<ul>
	<li>Paul Bruno, Atos Origin</li>
	<li>Daniel Schaefer, Kalis</li>
	<li>Pierre Queinnec, Zenika</li>
	<li>Joël Ceyzeriat, ST-Ericsson</li>
	<li>Werner Keil, emergn</li>
	</ul>

	<h2>Project Scheduling</h2>

	<ul>
	<li>December 2010 – proposal</li>

	<li>February 2011 - creation review and initial
	contribution</li>

	<li>March 2011 – First builds for early adopters</li>

	<li>June 2011 - First release aligned with Indigo</li>
	</ul>

	<p>And then releases aligned with the Mylyn project schedule</p>


	<h2>Changes to this Document</h2>

	<!--
	List any changes that have occurred in the document here.
	You only need to document changes that have occurred after the document
	has been posted live for the community to view and comment.
	-->

	<table>
	<tr>
	<th>Date</th>
	<th>Change</th>
	</tr>
	<tr>
	<td>14-12-2010</td>
	<td>Document created</td>
	</tr>
	<tr>
	<td>01-02-2011</td>
	<td>Updating interested Parties and Committers</td>
	</tr>
	</tr>
	<tr>
	<td>01-03-2011</td>
	<td>Updating interested Parties</td>
	</tr>
	</table>
	</body>
	</html>