Home » General (non-technical) » Project Proposals » New Mylyn Intents Project proposal
|
| Re: New Mylyn Intents Project proposal [message #652695 is a reply to message #651818] |
Sat, 05 February 2011 15:29   |
 Meinte Boersma
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).
Xtext blogs: executable models...again? | workshop material | custom scoping with Xtend
|
|
| |
| Re: New Mylyn Intents Project proposal [message #652868 is a reply to message #652726] |
Mon, 07 February 2011 12:43 |
|
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 |
Werner Keil
Messages: 1087
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 |
|
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 
Alex
|
|
| |
Goto Forum:
Current Time: Sat Apr 20 03:35:14 GMT 2024
Powered by FUDForum. Page generated in 0.03453 seconds |
] 
Search
Help
Register
Login
Home
