Intent/Project mission statement

• Alice looking at some code: «Hey, why is this thing designed this way ? It looks way more twisted than necessary»
• Bob : «Just check the design documents.»
• laughs

General purpose

An application has its own lifetime and quickly after the first major release is done, design choices are vanishing with the team being re-affected. Then most of the time spent on the software is dedicated to browsing through it, doing changes and testing those just to figure out the implications of the change.

Developers do write doc, but it’s just too much of a burden to maintain those. Mylyn did start to off-load the developer brain by leveraging the - invisible at that time – Task concept. With its recent re-structure, Mylyn scope has been broaden to the whole Application Life-cycle Domain, integrating Source Control Management, Continuous Integration and tooling support to practices like code reviews. Documentation is a major aspect of life-cycle management : just like Tasks have been transformed into a useful construction to the developer now that they have an associated context, document can turn into a real support for sharing knowledge about some design if keeping this documentation in sync with the reality is a no-brainer.

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. That’s what the Intent project is about.

Let’s take an example : a developer documents the general architecture of his software, 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.

Intent Spirit

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

Intent Components

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.

An extensible tool

This technology – just like Mylyn task focused UI – relies a lot on the integration it can have with other projects. Please refer to the Intent/Architecture to see how Intent can interact and be extended with other tools.