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.
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.
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 😉