Create useful documentation with Mylyn Intent : a step further in Application Life-cycle Management

Session Type: 
Standard [25 minutes]

Schedule info

  • 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

The facts: documentation update is a burden, so developers do not write doc

Quickly, documentation becomes useless, as it does not reflect the recent changes you made on your software. Sooner or later, no one will read it any more, and the design choices your team made will be lost. This has direct impacts on productivity and code quality: most of the time spent on the software is then dedicated to browsing through it, doing changes and testing those just to figure out the implications of the change.

Mylyn meets Intent: an IDE-integrated environment to author documentation and keep it synchronized with the real world

Mylyn did start to off-load the developer brain by leveraging the - invisible at that time – Task concept.
Documentation is a major aspect of life-cycle management: just like Mylyn Tasks, document can turn into a real support for sharing knowledge about some design, if keeping this documentation in sync with the reality is a no-brainer.

Providing a language mixing documentation and code on top of models is a promising way to help developers to provide useful documentation and to keep it up-to-date. Furthermore, integrating it directly in the IDE lowers the barrier of the documentation update and will allow cross-references with concrete development artifacts. That’s what the Intent project is about.

Talk - part 1: Getting to know Intent with a concrete use case

This talk is about introducing Intent to you through a concrete an example of usage.

  • We will see how the tooling will help in designing changes while updating the corresponding doc parts,
  • Moreover, we will see how doc validation can improve your code quality by allowing to specify new standards, less formal than checkstyle rules, but as important.

Talk - part 2: What's planned: integration with other tools and extensibility

In a second part, we will talk about what's planned for the future Intent releases:

  • Intent integration with Mylyn contexts and tasks: reference tasks directly in your doc, get the documentation parts related to a given task...
  • Collaborative features: using CDO's real-time updates and fine grained locks to allow team work around documentation
  • Pimp your Intent documentation by providing your own Xtext 2.0 editors, documentation languages, doc generators and synchronization mechanisms. Your documentation will be readable according to your criterias, not necessary ours.
  • Reduce the prerequisites skills required for Intent using by creating tools easing retro-documentation of existing softwares.

For more details about Intent, you can refer to: