Literate Blogging

Intent transcript is available - Agile ALM 2012

Tue, 03 Apr 2012 15:02:00 +0200

Last week was the Eclipse Con 2012, co-located with the Agile ALM Connect conference. I gave a talk about Intent, focusing on what Intent could bring to Agile practices. In a nutshell, Intent provides your documents with the ability to react to changes (in design or in code), turning them into true Agile Documents. You will also be able to capitalize on your work by defining high-level constraints on your projects that will be available in the future.

You can get the whole transcript of the talk just by clicking here.

The talk was a success, and a lot of people came afterward to talk about Intent and propose contributions or ideas. Please feel free to continue the discussion on the Intent forum, I’ll be glad to answer to any question, technical or not, and discuss about what could be done better.

I got really good feedbacks on the EclipseCon website, 19 +1 for 2 +0 and no negative feedback. I can’t resist to show you my 5 favorites:

And if you feel lazy, just take a look at these 2 demos (included inside the transcript) :

Intent 0.7 is waiting for your feedback

Thu, 27 Oct 2011 18:11:11 +0200

We are proud to announce that a first build of Mylyn Intent 0.7 is available. You can get it using the following update site: http://download.eclipse.org/intent/updates/interim/0.7.

You can use the Installation Guide to help you installing Intent.

To get started with Intent, we advice you to start with this tutorial.

We’re planning to release Intent fast and frequently, so your feedback (technical or not) is welcome !

You can provide us feedback by :

posting your questions, needs or ideas on Intent Forum
syndicating to Intent mailing list
filling the Intent FAQ
filing bugzilla issues ( “Mylyn” project / “Mylyn Docs Intent” Product )
contacting us on twitter

And while we’re talking about Intent, don’t forget that we will be at EclipseCon Europe 2011. Attend to our talk and discover how Intent can help you writing appealing, useful and up-to-date documentation, to constraint your software development, and all the cool features that we want to develop. And do not hesitate to meet and discuss with me, I’ll be really glad to get your feedbacks, good or bad.

Live Collaboration with Obeo Designer 6

Wed, 27 Jul 2011 14:10:00 +0200

I’ve been quite lucky these past few months : I’ve been given the opportunity to work on Collaborative features for our next release of Obeo Designer.

We had to make many choices and to define what was, according to us, a good collaborative process. In this post, you will see how Obeo Designer allows you to simply collaborate around models, through graphical representations such as Diagrams, Tables, Trees…

Why does SVN suck ?

I don’t think that I’m teaching anything to anyone here : collaborating on models through SVN can be a real burden.

For example, I often share models with all my teammates (typically our ecore meta-models). In order to avoid any concurrent modification on these models, that would force one of the developer to make a manual merge of the modified models (although this merge can be facilitated by EMF Compare, it remains painful, and quite a productivity killer), I first have to send a notification on skype to warn my team that I take the lock on some model files.

Well, it’s true that it does the work, but when I’m doing this it feels like I’m back to Stone age…

The main purpose of Obeo Designer’s Collaborative features is to avoid manual merge : we would like to rely on a mechanism that allows to lock models in order to avoid future conflicts.

Why cannot any SVN-based tool be the answer ?

As you may know, some SVN-based tools allow to lock files in order to avoid conflict. Although this allows to prevent from any merge if all users lock the files they are about to modify, there are 2 major issues, that we considered as blocking :

- the lock granularity : locking whole files does not seem to be the best solution when collaborating around models. Indeed, if an xmi file contains 1 000 model elements, and if a user A wants to modify one of these elements, he has to lock the whole model. Hence any other user that would like to modify an element contained in the same resource, but with no link with the element edited by user A, cannot modify the file. Another productivity killer : if modifications cannot be done by several users in the same time, you’re good to spend your day waiting in front of the screen… For Obeo Designer, we wished to have a fine grained lock mechanism, that allows users to lock one single model element, no matter in which resource it is located.

- the real-time updates : if a user A modifies a model element and commits, the other users would have to make an update to see these modifications. For Obeo Designer, we wished all users to see changes made by others in real-time.

Live Collaboration with O.D : example

But enough with the chitchat, here is a concrete example of live collaboration with Obeo Designer.

User A and User B are working on the same model, representing the stock of vehicles that should be repaired in a Garage. This model is located on a server (actually a CDO Repository, but the users do not need to know that).

User A creates a diagram on this Garage model :
User B creates a table on this Garage model :

User A decides to rename one of the cars. Obeo Designer automatically locks the modified element to avoid conflict. User A now sees the edited car as locked by him (green padlock) :
User B instantaneously sees that the edited car has been locked by another user, and cannot modify it anymore (but can edit any unlocked element, no matter if contained in the same resource) :
Notice that Obeo Designer uses lock strategies to determine which element should be locked when a modification is made. The default lock strategy locks the minimum set of elements that allows to avoid conflicts, but you can provide your own lock strategies (for example, if a car’s wheel is locked, also lock the wheel disk).
User A saves his diagram. Saving will trigger a commit on the server. Locks are released as there is no risk of conflict anymore :
User B sees in real-time the modifications made by other users :

As you can see, this automatic locks mechanism allows to avoid any conflict, and the end user does not need to ask himself which elements should he lock before doing a modification.

That said, it seems quite reasonable to let users to lock elements, if they know they are going to work on these elements and do not want to be bothered by other users’ work.

User A decides to lock the Garage and all its children :

he knows that no other user can edit these elements, and can work without fearing conflicts :

Such locks on demand are not automatically released when the user saves ; he will have to unlock them manually through the Lock / Unlock menu shown above.

End-User experience : is it too complicated ?

One of our main effort was to make live collaboration as simple and transparent for the end-user as it was possible.

Adding a resource located on the server is as simple as adding a local resource, except that the user will need to enter the server location (no magic here) :
Once it is done, automatic locks and real-time updates do the work without requiring any knowledge from the end-user.

Our first customers feedbacks are enthusiastic, and we can’t wait to release the Obeo Designer 6 to see how people reacts.

Thanks to the CDO team !

We used CDO to develop these collaborative features.

If this name does not ring a bell to you, I strongly advice you to take a look at CDO wiki, and to play a bit with it. It is truly a great framework, extensible, stable and really fun to play with ! Eike Stepper, Martin Fluegge and all the CDO team have been a really great support. I do not think we would have been able to get to this result without them. Just yesterday, Eike fixed an issue less than 30 minutes after I’ve opened it. Thanks a lot guys !

And there is much more…

Well, there is truly a lot to say about these collaborative features, I’ll definitely write new posts to show you representations sharing (in this mode, the users also share their diagrams, tables and trees), changes serialization (so that an end-user can save locally its work without committing it, keeping the locks to avoid conflicts), user identification… We also have many cool features in mind, I’ll present these when time will come ;)

Intent Discovery - Part 1 : the intents behind softwares

Wed, 02 Feb 2011 09:25:00 +0100

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

Nowadays, you can find tools for basically any Developer or Architect task, no matter how complex. How come, then, any developer will tell you how hard it is to achieve a task as simple as updating a doc ?

When it is a 500 pages bloc and the feature you developed should be mentioned in 15 different chapters, you may even spend more time updating doc that you have spent developing and testing the feature itself… Any big software released at least 2 years ago contains errors in its documentation, as no one has time for reading the 500 pages and check the doc consistency.

This post is tempting to explain :

Why the knowledge behind softwares cannot be properly captured without Documentation
Why Documentation update is a nightmare
How Intent, by representing Documentation, Models and development artifacts as a whole, and providing tooling for writing useful doc, will try to reconcile developers with documentation writing.

The intents behind softwares

Intent claims itself to be a tool helping developers to write doc. But what is doc exactly ? Too many times, I hear developers saying things like “just read the doc”, when actually they are talking about javadoc. Don’t misunderstand me, javadoc is great, and I use it all the time and rigorously. But such a doc is so tight with code structure that it is not appropriate to show the intents behind a software : how would I explain the design choices I made when focusing on a Java Class ?

I should not have to stress out how important are concerns and design choices understanding : first of all, when your team grows up, newcomers should quickly and fully understand the spirit of your software architecture, to be able to maintain and to improve your software (which is basically what they are paid for). What is more, I challenge you to explain clearly the design choices you made on a project six months ago ; I am sure that you will forget an important concern.

To present the intents behind softwares, developers do write doc, although they are often doing it because of their project manager pressure. Such “paper doc” is written with pure documentation languages (like Textile, MediaWiki, Latex, HTML, open office…). I think any developer who had to maintain this kind of doc up-to-date with the changes made on their software will agree : paper doc synchronization is quite a burden. How come achieving such a common task should be so difficult, comparing to all the complex tasks we handle everyday thanks to the appropriate tooling ?

Code, Models and Documentation desynchronization

Let us consider the different ways that can be used to represent the knowledge behind a software. We identify three different spaces, each space bringing a different kind of knowledge to the software.

The Technical Space contains you source code and all your configuration files. It brings a concrete knowledge of the software, describing exactly its properties and what it is going to do. It is hard to capture the intents behind the software from this viewpoint : for example, it is nearly impossible to determine what part of the code allows to fulfill a given requirement. Again, javadoc’s scope is too reduced to allow high-level knowledge sharing (“I see the trees, but where is the Forest ?”).

The Model Space brings a more formal knowledge of your software : it allows to formalize requirements and to specify your software’s main entities and architecture. However, it is still very hard to determine, by studying models, the design choices that have been made by the Architect, and the underlying concerns and requirements from which they have been decided.

The Document Space provides a global knowledge of your software. Using natural language, it is way easier to explain the intents behind the models and code. Moreover, it is structured following a stream of consciousness order : one can structure a document by concerns (one part for all the code and models that ensure persistency of datas, one part dealing with security issues…), another would prefer to structure it following each requirements… In result, a reader will be able to discover the software step by step, with an high-level view of each main requirements and design decision.

These 3 spaces all provide useful informations about your software. However, if synchronization between Models and Code has been improved during the last few years (with code generation tools like Acceleo, Traceability tools, and reverse engineering tools), there is clearly a lack of automatic processes to keep documentation up-to-date with the Model and Technical spaces.

Intent provides tooling for keeping the documentation up-to-date with any Model, as it will be detailed in next posts. As any development artifact (whether it is a Java class, a plugin dependency, an Acceleo script, a Mylyn task…) can be represented as a model, Intent will allow to synchronize the documentation with any “concrete” information.

Intent’s purpose : reconcile developers with documentation

Intent provides tooling for :

creating a complete documentation. As each developer has its favorite paper doc language, the concrete syntax for the documentation will be opened (one can choose Textile, another one HTML or Latex).
defining model fragments with a textual syntax. As it has been shown by all the M.D.E. users, DSLs are a good way to simplify design. That is why Intent will provide extension points to allow users to use the correct textual DSL according to what they want to describe (for example, one DSL for describing your plugin dependencies, and an other for describing Ecore models). Such DSLs may be created from scratch or through the use of Language Development Frameworks like Xtext.
an authoring tool with appropriate tooling, allowing users to search for all documentation parts related to a concern or a model element, to compile and validate the described models, providing code completion and quick-fixes…
synchronizing the described model fragments with the concrete world
referencing precisely development artifacts directly inside the documentation (for example : “the development of this feature has been divided in 3 tasks : <reference to the corresponding mylyn tasks>”).

Writing doc becomes as fun and useful as writing doc !

An important point to notice is that Intent allows developers to start writing code and synchronize it with their doc or writing doc and synchronize it with their development artifacts ; just use the right tool for the task.

Benefits of writing documentation with Intent

I am aware that I have not presented enough features of Intent to convince you of all the benefits it brings. Let me leave you with some benefits based on common sense.

First of all, as Intent is fully integrated to the Eclipse IDE, you will not have to toggle from your IDE to Open Office any more. As it is compliant with all design tools (graphical modelers for example) and all the Eclipse projects for which bridges will be developed, writing doc is no longer a burden.

As updating documentation becomes straightforward, doc is now really useful : it finally describes your software, and not what your software used to look like 2 years ago. As the documentation related to a part of code or model is kept around its definition, it is very easy to search through the documentation and find all code related to one concern, or all concerns related to a Class. Of course, a doc up-to-date improves the maintainability of your software, and will help to avoid misunderstanding issues. Such a doc also provides a high-level knowledge of your software. Donald Knuth speaks about Bird’s Eye View.

Actually, your doc becomes more than a doc : you can use it for synchronizing all your development artifacts, from requirements coverage to development environment.

Many other benefits related to collaborative design, developers daily work and Application Lifecycle Management will be presented later.

Next post : How does the Intent syntax allow to split design across concerns

If you liked this post, you can read the Eclipse proposal of the Intent project and provide us feedback here. If you want to follow the Intent project, go check our Twitter account.

Provide a doc ad hoc with Intent

Mon, 27 Dec 2010 16:00:00 +0100

Soon on this blog : everything you will need to know about the Intent project, soon to be part of the Mylyn project - proposal is in the work.

The main purpose of Intent is to allow developers to easily write a documentation up-to-date with any development artifact (models, code, environment…). The documentation, integrated with other Eclipse tools, then becomes truly useful and is no longer a burden that developer have to carry to please their customers or their project manager.

Based on Donald Knuth’s Literate Programming concepts and allowing collaborative work around design tasks, Intent will be presented at Eclipse Con 2011.

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

Donald Knuth, Literate Programming (1984)