Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Newcomers » Proposals » New Mylyn Intents Project proposal
New Mylyn Intents Project proposal [message #651818] Tue, 01 February 2011 17:31 Go to next message
Wayne Beaton is currently offline Wayne BeatonFriend
Messages: 503
Registered: July 2009
Senior Member
From the project 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.

For more information:

http://www.eclipse.org/proposals/mylyn.docs.intent/

Your feedback is invited.

Wayne
Re: New Mylyn Intents Project proposal [message #652695 is a reply to message #651818] Sat, 05 February 2011 15:29 Go to previous messageGo to next message
Meinte Boersma is currently offline Meinte BoersmaFriend
Messages: 434
Registered: July 2009
Location: Leiden, Netherlands
Senior Member
I have some concerns:

First of all, documentation typically exists on a different level (or should we say: plane) of existence as concrete (code) artifacts. If that weren't the case, the documentation is probably either useless (e.g., the "/** Returns the list */ public List getList() {...}" type of Javadoc) or formal enough to be used as a model instead, in which case we'd have true literate programming. This "semantic gap" always makes the coupling between code and documentation (especially "Bird's Eye View" documentation) quite loose. I'd say that having the (modelized) documentation be an annotation of the code is necessary to bridge that gap (somewhat). This means that the documentation should be able to point towards code artifacts, e.g. Java classes (easy enough with Xtext). Intent could add huge amounts of value by being able to annotate specific cross-cutting aspects (in the sense that these aren't already specified in a single place in the code), such as OSGi dependencies, in a comfortable and built-in way. (Btw: I think this is already in the proposal, but it isn't entirely clear to me.)

Second concern is the absence of the word "change" in the proposal: considering that software is in constant flux, I think Intent should have a clearly defined use case with respect to change. In any case, we should be able to treat documentation as code in the sense that errors in the documentation (e.g., pointers to classes) should be considered compiler errors. I'd imagine a check on the (non-semantic as a true semantic check requires an A.I.) validity of the documentation could/should be part of the continuous integration.

Third concern is the ability to introduce abstractions or new concepts into the documentation language: even when only documenting for a fixed set of concerns, patterns and abstractions tend to become apparent over time. It's helps both the software development as such as well as the documentation discipline to be (made) aware of these patterns/abstractions and be able to document them at that level (of abstraction).


Re: New Mylyn Intents Project proposal [message #652726 is a reply to message #652695] Sat, 05 February 2011 22:06 Go to previous messageGo to next message
Fabian Steeg is currently offline Fabian SteegFriend
Messages: 72
Registered: July 2009
Member
Just a quick thought about your third concern, the introduction of new abstractions: from what I understand from Alex' blog post the idea is to plug custom DSLs into the documentation language, see http://alagarde.tumblr.com/post/3064712740/intent-discovery- part-1-the-intents-behind
Re: New Mylyn Intents Project proposal [message #652868 is a reply to message #652726] Mon, 07 February 2011 12:43 Go to previous messageGo to next message
Alex Lagarde is currently offline Alex LagardeFriend
Messages: 185
Registered: May 2010
Senior Member

In response to Meinte Boersma concerns :

1/ That is one of the major feature of Intent : you can reference any concrete development artifacts (Java classes or methods, model elements, plugin dependencies...) in the doc, as long as it is possible to represent it as a model.

One can imagine defining new clients for Intent (see http://wiki.eclipse.org/Intent/Architecture) that extract all parts of the doc that references a Java Class (for instance) and generate a javadoc from these.

2/ You speak about 2 different things : reaction to change and documentation validation.

As Intent allows to keep code, models and doc synchronized, reaction to change is a major concern.

When you have to add new requirements or update specification, you can change the Intent documentation. Intent then determines any inconsistency between doc and "real world", generates synchronization error markers and propose quick-fixes to update doc or code (for example : "You speak in the documentation of a Java class that does not exist in your workspace").

When you develop your software, you may define new API methods or modify the model. Intent can detect these changes and will add synchronization issue markers in the document (for example : "You have define an API method in your workspace that is not defined in the documentation").

The main question is when the synchronization between development artifacts and documentation should be launched : launching a synchronization every time the doc or the code is updated seems to be an overkill. One can imagine a "synchronize" button in Intent UI, allowing to launch a synchronization explicitly. One can also imagine that syncronization is in seamless integration with Hudson : when hudson builds a new version of the code, synchronization is launched.

Validation of the development artifacts defined in the documentation has also been specified : all development artifacts described in the documentation (inside @M ... M@), when restructured and compiled by the Intent compiler, are validated using the standard EMF Validation framework. Therefore you will be able to easily add new validation rules for your software (for example : All public method of an API class start with "api", all Action of a context menu should respect a certain naming rule...).

In regards to the validation of the documentation itself, we have many ideas (documentation coverrage, checks on chapter sizes...), that you will discover soon.

3/ Fabian pointed out the capability of defining custom DSLs that you will be able to use in the documentation to describe new concepts.

You will also be able to define new connectors allowing to synchronize any "real world artifact" with the documentation.

Let's take an example : I want to describe the UI of my application.

To do so, I define a custom DSL with Xtext allowing to describe an UI feature. When parsed, this DSL will produce an instance of my custom metamodel "UIFeature".

For example, I will be able to define an Action as above :
@M definitionOfMyContextAction1
editorContextMenu {
     actions += new ContextMenuAction {
              name = "myContextAction1";
              icon = "platform:/plugin/myUIProject/icons/ic1.png";
              javaClass = "myUIProjet.ui.actions.action1";
     }
}
M@


If I want Intent to be able to determine if the UI features described in the documentation are correctly implemented in the code, I will define a new Synchronizer, that will search for all pop-up menus, wizards and actions registered in the projects of my workspace, and produce an "UIFeature" model out of it. Intent will compare the model produced using "real world" informations with the model described in the documentation (using EMFCompare). Any inconsistency will lead to synchronization issues markers.

Therefore, when a developer has to define a new UI-related feature, he will also have to document it. If validation rules are defined for the "UIFeature" metamodel, they will be applied on any pop-up, wizard or action description. For instance, you will be able to control action naming, icon locations, be sure that an explanation of each action has been added in Eclipse Help...

I hope I have answered to your concerns.
We are currently writing the Intent wiki, maybe the "Use case" section (http://wiki.eclipse.org/Intent/Use_Cases) will help you to see how Intent links documentation and development artifacts.
Alex
Re: New Mylyn Intents Project proposal [message #653895 is a reply to message #651818] Fri, 11 February 2011 18:10 Go to previous messageGo to next message
Werner Keil is currently offline Werner KeilFriend
Messages: 1083
Registered: July 2009
Senior Member
Hi,

First of all, although combined with the word "Mylyn" or "Mylyn-Docs" it may
be a bit better, but generally I find the name "Intent" for the project very
unlucky and not descriptive.

"Design Intent" barely seems a word even used in Software design or
Requirements Definition.
2 places found are 2D CAD: http://www2.ivcc.edu/perez/Design%20Intent.htm
or The Energy Systems Language
http://en.wikipedia.org/wiki/Energy_Systems_Language#Design_ intent
(an interesting form of DSL btw, maybe it mabe it can use Xtext or other
parts of EMF, note also http://en.wikipedia.org/wiki/Buckminster_Fuller, I
believe he must have inspired Eclipse Buckminster at least partly ?;-)

Aside from that, the word "Intent" has been largely predominated by Google
Android and the Mobile Ecosystem around it, including some Eclipse projects
like Sequoyah. Misunderstandings, especially when Design or Requirements for
the growing space of Mobile apps was "intended" ?;-)

I don't know Mr. Knuth, or his thesis, but many parts of the proposal indeed
sound inspired by this much older idea of Design Rationale:
http://en.wikipedia.org/wiki/Design_rationale
Interestingly, there "Decision Recommendation and Intent Model" (DRIM)
contains the word "Intent", but it wouldn't stick out more than others.
Wrapping it up, "Requirement" or "Requirements" seems a more commonly used
term.

As part of the "Docs" subproject of Mylyn, it seems, the new proposal of ECR
(Enterprise Content Repository) has far more synergies to offer, than CDO
which intends to store EMF models mostly. The proposed architecture:

>Repository : fundamental properties
>In order to wrap the concrete technology used to store the Document and
>manage concurrent accesses, we have defined the Repository interface.
>Any Repository must provides the following features :

>access to any element of the Document from an URI (REST-oriented API)
>provide transactional mechanisms for saving/rolling back changes made on
>the Document
>notify all subscribed clients of any modification made on listened elements

Is in large portions almost identical to the Eclipse ECR Proposal, and other
Document-centric repository systems like JCR (Java Content Repository)
Indeed, BEA Systems, now Oracle has used EJBs underneath some of its JCR
implementations, so that is possible, but a Document Repository shouldn't
try reinventing the wheel or tweak and abuse other forms of repository if
both more appropriate standards and Eclipse proposals exist out there
already.

As Doc2Model committer, JCR 2.1 EG Member and constantly involved in Agile
Design and Requirements Gathering I would be happy to provide input and help
beyond this forum, and also consider myself an Interesting Party. Please
list me ("Werner Keil, emergn") as such if possible.

Werner
Re: New Mylyn Intents Project proposal [message #654591 is a reply to message #653895] Wed, 16 February 2011 12:33 Go to previous messageGo to next message
Alex Lagarde is currently offline Alex LagardeFriend
Messages: 185
Registered: May 2010
Senior Member

Hi Werner,

first of all, thanks for the interest and for your questions.

1/ I am personally quite pleased with this name : "Intent" is used to show and capitalize on the intents behind softwares (see http://tinyurl.com/45os7u6), a bit like Mylyn's Task, providing a tooled environment to manipulate tasks behind softwares development.

2/ Design Rationale share some of the concerns of Intent, it is true, but it requires a much more formal and constraining approach. Intent is trying to reconcile developers with documentation, by lowering the barrier between doc and development artifacts. With Intent, you can start writing code and then explain in the doc your design choices and the intent behind them, or use a more formal approach (that one can see as "Document Driven Design"). Tooling will provides facilities for synchronizing doc and development artifacts.

3/ Repository, ECR and CDO

The Repository concept used in Intent is just an Interface, and does not rely on any concrete technology. If for now on we propose an implementation of such Repository using CDO and an other one using the Eclipse Workspace, an implementation based on any other technology can be developed (see http://wiki.eclipse.org/Intent/Architecture).

This Repository does not store the documentation itself, but models representing this documentation (and many other informations, like compilation/validation/synchronization issues, traceability informations...). From what I understood of ECR proposal, I think that the best use of ECR in Intent will be to generate the Documentation inside such Repository. This can be easily done by defining a new Intent Client, that may be part of future releases.

4/ We are glad to count you as an interested party. I let you know when it you will be listed as such.

If I did not make myself clear enough or if you have other questions, I'm here Wink
Alex
Re: New Mylyn Intents Project proposal [message #660288 is a reply to message #654591] Thu, 17 March 2011 16:42 Go to previous message
Alex Lagarde is currently offline Alex LagardeFriend
Messages: 185
Registered: May 2010
Senior Member

Creation Review succeeded, on our way to initial contribution Smile

You can still send us feedbacks, we will be glad to answer.

[Updated on: Thu, 17 March 2011 16:42]

Report message to a moderator

Previous Topic:Eclipse Runtime Analysis Tools
Next Topic:Cinnamon
Goto Forum:
  


Current Time: Thu Nov 27 04:47:49 GMT 2014

Powered by FUDForum. Page generated in 0.02115 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software