Da Graphical Modeling Framework (GMF) has ever been an amazing, very productive and powerful project to generate diagram for models based on EMF. However, I recently read several things and forums or had some chatting with people that make me think GMF is difficult to use for newcomers. GMF is not that complicated to understand and use, but the feedbacks I got show that it is not easy to get it, it can be a blocking issue for some potential users. The question is “what can we do to make it easier for people to consume GMF?”.
The first answer I have is in refactoring documentation to show more “Getting started” tutorials. Then people need to spend less time to find a way to get started.
What you see on the main GMF wiki page
Also, I thought the tutorial was too monolithic. There are a lot of things you can do with GMF, but not all will be useful for your use-case. Users need to clearly understand what use case of piece of documentation actually resolves, in order either to skip it, or to spend more time on it. This can be achieved by reorganizing the titling of the documentation. Then it becomes easier to find out what are the different steps when creating a diagram, which ones you can skip, which ones interest you.
Structured organization and titling
Finally, by digging into current GMF documentation, I discovered that GMF has lots and lots of resources to help people to leverage it. There are several tutorials, including one that includes Flash videos to show how to generate a diagram. This is a very-high value resource, but it was unfortunately not very easy to find. This resource deserved to be highlighted! A sad thing is that (AFAIK) there is currently no way to integrate these movies into the wiki. I hope Bug 352735 gets fixed soon so that people will really benefit from these tutorials without effort.
If you know anything you could improve to the refreshed documentation, please do it. Remember of your first experience with GMF or of the first time you met a classical use-case: How did you search answer? How could the answer be easier to find? How could the answer be easier to understand? What in the documentation makes it less efficicent? If you have ideas, feel free to edit the documentation accordingly.
I learnt a few lessons from this work:
- Very new users are really the people to target for tutorials.
- For tutorials, a video is more attractive and efficient than 5 pages of documentation.
- Do not try to be exhaustive in tutorials, prefer being modular or pluggable, so that the tutorial remains easy to follow, and that people can extend it by adding a sub-sub-title. It will make the tutorial easier to maintain, without making it easier to read (people are able to skip your “tutorial modules”)
- Make your tutorial incremental. Resolve use-case one after the other. Be very explicit about the use-case. People need to understand where and why you go before reading the “How”
- Sometimes, there is alreadly a lot of documentation available, there is no need for more. Instead, it can be useful to spend time on organizing documentation and making it more visible. A documentation that nobody finds or reads is very sad, it is waste.
These are my very first steps with documentation, and my first thoughts after working a little bit on GMF documentation. There are probably some things you’d like to tell me on this topic according to your experience. I’d be glad to learn from you, please tell me 😉
Some Eclipse stuff 
#1 by Niels Brouwers on July 22, 2011 - 11:42 pm
Hi Mickael,
Having a few years of practical experience with building DSLs, defining model transformations and modeling in general, I found using GMF to build a graphical editor being one of the most complex tasks I’ve come across during that past years. I must admit I lack a decent background in Java programming and building graphical editors, but I’ve spent effort enough to experience the steep learning curve to even begin with using GMF. Even modifying existing GMF models, for example the models used by the UML2Tools project to build a UML modeling environment, can be quite complicated.
The last attempt to build a very simple graphical editor using GMF stranded because I could not get compartments to work properly:
http://www.eclipse.org/forums/index.php/m/673671/#msg_673671
I’ve read and followed the examples within the DSL toolkit book written by Richard Gronbach, read several tutorials and read numerous of articles on the Eclipse GMF forum, followed an Eclipse EMF/GEF/GMF course taught by Arthem Tikimorov and really do understand the general concepts and procedures to create diagrams. However, I found myself struggling with creating new and modifying existing diagrams, even with the most simple use cases.
In my opinion, it is logical that companies like (former) Borland and Obeo develope(d) more abstract DSL toolkits on top of GMF, respectively Borland Together and Obeo Designer. Maybe GMF is just too complicated, too enormous and too low-level to be used by a ‘normal’ DSL toolsmith. Unsufficient documentation just might be a symptom, while the problem might be the complexity of GMF itself.
Still, if you attempt to improve the documentation, I would obviously appreciate the effort. However, it is hard to pinpoint exactly what to improve. Maybe it is just a matter of more and better documentation. Distinguish between ‘monkey-do-monkey-see’ exercises simple enough to execute, but complex enough for illustrating purposes within tutorials. Provide extensive reference documentation for advanced use cases. But most importantly, provide a better conceptual view somewhere below the different kinds of models (tooling, graphical and mapping models) and above the code level.
I hope this helps. Feel free to contact me if I can do something to help.
Best regards,
Niels Brouwers.
#2 by Mickael Istria on July 25, 2011 - 11:20 am
Hi Niels,
Thanks for your feedback.
What appears is that in order to be able to customize GMF, you need to have good knowledge of Eclipse RCP (such as SWT, Draw2d or GEF). It is not a requirement to get started with GMF, but it is often a requirement to get it working as you want.
Having a very good GMF editor does not only requires Modeling skills but also good Eclipse development skills.
I agree with the logical reactions from Modeling companies such as Obeo to make layer on top of GMF, to make it easier and more productive for their use-cases.
I keep in mind your advice for a “conceptual view” of GMF. I’ll try to work on it. If you think you could contribute anything to it (a conceptual diagram or a few sentences) that could be shown of the main wiki page of GMF, please do it.
Regards,
#3 by Ivar on October 3, 2011 - 3:28 pm
Hi Mickael,
Thanks for your article.
One suggestion: Try to gather the documentation at one place.
I like how Graphiti does this to a considerable degree, showing what’s officially supported.
Furthermore, you say one needs to have a good knowledge of Eclipse RCP (GEF, etc) in order to customize GMF. I’ve read the GEF book (Rubel, Clayberg, Wren) and actual editing is done in the last chapter of the book, so GEF seems quite complex itself.
How long time would you say one should use before one is able to customize GMF? As someone familiar with Java, but not with the Eclipse RCP development (SWT, Draw2d, extension points, GEF, etc.). Also, I must admit I’m curious, how long have you been doing Eclipse RCP development full time?
Thanks,
Best regards
#4 by Mickael Istria on October 4, 2011 - 12:37 pm
> One suggestion: Try to gather the documentation at one place.
Can you be more explicit. Maybe you could an issue for that on Eclipse bugtracker: https://bugs.eclipse.org/bugs/enter_bug.cgi?product=GMP
> How long time would you say one should use before one is able to customize GMF?
Without any knowledge in RCP, I think you’ll need a 2-3 days to get your first small customization working. After that, I don’t really know, it highly depends on you 😉
I think if you know GEF, you can already start customizing. Most of customization relies on the same stuff as GEF (Figures, EditPolicies…)
> Also, I must admit I’m curious, how long have you been doing Eclipse RCP development full time?
I’ve never workded “full time”, I also spend time on mailing-lists, forums, reading articles, dealing with build-stuff, trying somne new products… But I’ve been an Eclipse plugin/RCP developer for 3 years and half now (I feel old!)
#5 by Ivar on October 4, 2011 - 11:37 pm
Thanks for the reply Mickael!
“Can you be more explicit.”
Well, from your post you link to quite a few pages, so it just seems there are so many entries into GMF, and many places where recipes are shared.
Conversely, for Graphiti, there is one official guide located at help.eclipse.org. (To be honest there’s also an FAQ which not all people find and so on. So there’s room for improvement also there.)
To take an example:
http://www.eclipse.org/modeling/gmp/
Under “Getting started”:
The “Online documentation” links to http://help.eclipse.org/ganymede/index.jsp
This must be wrong..?
In the current http://help.eclipse.org there is no GMF documentation. I don’t know if this is intentional? (If I recall correctly GMF was back on the Indigo release train..?)
The “tutorial” links to a page.. which simply has a link to an other page.
I hope I don’t sound too much of a whiner, but it just strikes me as a bit messy. I’ll file a bug of course if you think this is reasonable…
#6 by Mickael Istria on October 5, 2011 - 10:41 am
I tend to say that the main and best entry point for GMF is the wiki: http://wiki.eclipse.org/Graphical_Modeling_Framework
However, it is true that GMF also contributes to the “standard” Eclipse help. I am not sure this is the most powerful and most agile: help is generated once per release, and it is not easy for non-committers to improve it. The only thing I’d like to see on help.eclipse.org is JavaDoc.
There are indeed some improvements to do on the eclipse.org/modeling/gmp website, but I don’t have the permission to improve it…
A bug currently prevent GMF to contribute to Indigo help: https://bugs.eclipse.org/bugs/show_bug.cgi?id=359948
I’ll open a topic with your feedback on the gmf-dev mailing list. Feel free to participate! Mailing-lists and bugs are clearly a more efficient way to express your opinion about GMF than blog post comments.
#7 by LuisCM on July 23, 2011 - 4:13 pm
@Legal