Create useful documentation with Mylyn Intent: a step further in Application Life-cycle Management
- 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.
The facts: documentation update is a burden, so developers do not write doc
When developers make a modification on the code, how many of them has the time to browse through the hundred of pages of documentation just to find where to document the changes, and check the whole doc consistency afterward ?
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 vanish. 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 your software (design choices, requirements...), 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 (Java code, plugin dependencies, models, code samples on the Internet...). That’s what Mylyn Intent project is all about.
Intent allows to close the gap between Requirements, Design choices and development artifacts as they are referenced inside a same document.
- Bob reviewing Alice's recent commits: Why did you define tests related to this new Action inside the test.ui plugin ?
- Alice: Why, where do you want me to define them ?
- Bob: Don't you know that any test related to Actions should be located in the test.acceptance plugin ? Didn't you read the dev guidelines ?
- Alice: Yes, when I started the project, but I don't have time to read it everyday...
Moreover, Intent provides tooling for checking automatically your software standards (dev guidelines, processes and good practices...).
Such mechanism will make the team stick to the same standards & processes automatically. In result, you'll spend less time reviewing the code, and will be able to focus on the dev itself.
Talk - part 1: Getting to know Intent with a concrete use case
This talk will introduce Intent through a real life use case.
We will see how the tooling will help in designing changes while easily updating the corresponding doc parts.
Moreover, we will see how Intent validation mechanism can improve your code quality by detecting any issue with the standards you judge important (test coverage, User guide documentation for each new feature...).
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.